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PREFACE 


In  the  nearly  seven  years  since  its  initial  release  in  the  fall  of  1985,  Microsoft  Windows  has 
established  itself  as  the  industry-standard  graphical  environment  for  personal  computers 
built  around  Intel  microprocessors.  PROGRAMMING  WINDOWS  is  not  quite  as  old  as 
Windows  itself,  but  the  second  edition  is  now  almost  two  years  old,  and  the  release  of  Win¬ 
dows  3.1  necessitated  some  revision. 

This  third  edition  has  several  changes.  First,  all  programs  are  now  compilable  with 
either  the  Microsoft  or  the  Borland  compiler.  All  make  files  are  generic  and  use  environ¬ 
ment  variables  for  compiler  flags,  link  libraries,  and  so  forth.  Second,  all  programs  are  now 
compilable  in  C++  mode.  Although  I  don’t  use  any  C++  specific  features,  compiling  first  in 
C++  mode  is  helpful  if  C++  features  are  to  be  added  later  to  the  code. 

Because  Windows  3.1  runs  only  in  protected  mode,  I  have  revised  some  text  and  pro¬ 
grams  to  take  advantage  of  that.  Generally,  working  with  memory  in  Windows  is  easier  in 
protected  mode  than  in  real  mode. 

The  chapter  on  text  and  fonts  focuses  on  another  Windows  3.1  enhancement — the 
introduction  of  the  scalable  outline  font  technology  known  as  TrueType.  The  chapter  on 
DDE  now  also  includes  information  on  the  DDE  Management  Library  included  in  Win¬ 
dows  3.1.  Throughout  the  book,  Eve  made  use  of  the  new  Common  Dialog  Box  Library.  In 
addition,  I’ve  added  more  information  on  device-independent  bitmaps  (DIBs)  and  owner- 
draw  buttons,  which  were  enhancements  to  Windows  3.0. 

Since  the  publication  of  the  first  edition  of  PROGRAMMING  WINDOWS  in  early 
1988,  many  programmers  have  told  me  that  the  book  has  been  useful  in  helping  them  learn 
how  to  write  applications  for  Windows — an  environment  that  is  quite  different  from  the 
character-mode  interface  of  MS-DOS.  Nothing  could  make  me  happier. 

It  was  my  intention  with  the  first  edition  of  PROGRAMMING  WINDOWS  to  show  the 
basics  of  writing  programs  for  Windows  using  the  C  programming  language.  A  book  like 
this  cannot  begin  to  delve  into  the  complexities  of  a  full-fledged  application  program,  of 
course,  but  it  can  show  how  to  handle  all  the  various  components  of  a  Windows  program.  It 
is  up  to  the  application  programmer  to  merge  these  components  into  a  coherent  whole. 

Windows  has  the  reputation  of  being  easy  for  users  but  tough  for  programmers. 
Aspiring  Windows  programmers  often  face  a  steep  learning  curve  and  want  to  see  lots  of 
programming  examples.  To  satisfy  that  need,  this  book  contains  over  50  complete  pro¬ 
grams.  Many  of  them  are  short  and  stripped  down  to  clearly  illustrate  various  Windows 
programming  techniques.  Others  are  a  bit  longer  to  show  how  everything  fits  together. 
Several  of  the  programs  are  useful  utilities.  Others  are  tools  for  exploring  Windows. 

What  I  don’t  do  in  this  book  is  teach  you  how  to  use  Windows.  If  you  have  no  ex¬ 
perience  using  the  environment,  now  is  the  time  to  install  it  and  play  with  it  for  a  while. 
Windows  is  very  easy  to  learn. 
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Nor  do  I  teach  you  how  to  program  in  C.  Before  you  even  think  about  programming 
for  Windows,  you  should  have  a  good  working  knowledge  of  programming  in  C  for  a  more 
conventional  environment  such  as  MS-DOS.  If  your  C  is  a  little  rusty,  you  may  want  to 
spend  some  time  becoming  better  acquainted  with  the  topics  of  structures  and  pointers. 

A  good  familiarity  with  the  segmented  architecture  of  the  Intel  x86  family  of  micro¬ 
processors  will  also  help.  If  you  know  how  x86  addressing  works  (in  both  real  mode  and 
protected  mode)  and  the  difference  between  near  and  far  pointers  and  functions,  you’re  in 
good  shape.  For  those  readers  who  don’t,  I’ve  included  some  explanations  along  the  way. 

To  compile  the  programs  in  this  book  and  to  write  your  own  programs  for  Windows, 
you  need  one  of  the  two  following  software  packages: 

■  Microsoft  C/C++  Professional  Development  System  for  Windows 
version  7.0. 

■  Borland  C++ 3.1. 

If  you  haven’t  yet  installed  your  compiler,  you  should  know  that  the  programs  in  the 
book  require  only  the  small-model  libraries.  You  may  be  able  to  use  a  C  compiler  other 
than  Microsoft’s  or  Borland’s  if  the  compiler  is  suitable  for  compiling  Windows  programs. 
Most  other  C  compilers  can’t  be  used  for  this  purpose. 

To  best  run  Windows  and  the  development  tools,  you  need  the  following  hardware: 

■  An  IBM  personal  computer  (or  compatible)  based  on  the  Intel  80386 
microprocessor  with  a  hard  disk  and  4  megabytes  (MB)  of  memory 
running  MS-DOS  3-3  or  later. 

■  A  graphics  display  and  video  board,  preferably  compatible  with  the  IBM 
VGA  (Video  Graphics  Array)  or  better. 

■  A  mouse.  Although  a  mouse  is  generally  optional  for  most  Windows 
programs,  some  of  the  programs  in  this  book  require  one. 

Sometimes  readers  of  computer  books  are  curious  about  the  author’s  own  system. 
When  I  wrote  the  first  edition  of  PROGRAMMING  WINDOWS  in  1987,  I  used  an  IBM 
PC/AT  Model  339  (8  MHz)  with  two  30-MB  hard  disks,  512  kilobytes  (KB)  of  memory  on  the 
system  board,  and  a  1.5-MB  Intel  Above  Board  PS/AT.  The  system  included  a  Microsoft  bus 
mouse,  an  IBM  256-KB  Enhanced  Graphics  Adapter  (EGA),  and  an  NEC  MultiSync  monitor. 
I  wrote  the  book  using  WordStar  3-3  and  printed  everything  on  an  IBM  5152  Graphics 
Printer. 

For  the  second  edition,  which  I  revised  in  1989  and  1990,  I  used  a  20-MHz  IBM  PS/2 
Model  70  with  a  120-MB  hard  disk,  6  MB  of  memory,  an  IBM  8514/A  graphics  board 
(although  I  generally  ran  Windows  in  VGA  mode),  an  NEC  MultiSync  4D  monitor,  and  a 
Microsoft  mouse.  By  that  time,  I  had  abandoned  WordStar  and  used  Microsoft  Word  for 
revising  the  book  chapters,  printing  on  an  NEC  SilentWriter  LC-890  PostScript  printer. 
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For  the  third  edition,  I’m  now  running  Windows  on  a  Northgate  Elegance  433  (486-33) 
with  a  300-MB  hard  disk,  8  MB  of  memory,  and  various  VGA  and  super-VGA  boards.  I’m 
also  now  using  Word  for  Windows  2.0. 

A  book  such  as  this  could  not  have  come  about  without  help  and  encouragement 
from  some  very  special  people.  I  offer  my  heartfelt  thanks  with  a  handshake  or  hug  (as 
appropriate)  to  the  following  people: 

■  To  everyone  at  Microsoft  involved  in  Windows  3.0  and  3.1,  for  creating  a 
system  with  fascinating  depth  and  seemingly  endless  things  to  learn. 

■  To  all  the  Windows  3.0  developers  who  reviewed  chapters  in  the  second 
edition  and  offered  comments  and  suggestions:  Clark  Cyr,  David  D’Souza, 
and  particularly  David  Weise. 

■  To  the  MS  Online  System  Support  people  in  the  Windows  SDK  group  who 
reviewed  galleys  of  the  entire  second  edition.  Much  gratitude  to  Todd 
Cole,  who  volunteered  his  group  and  coordinated  the  effort;  special 
thanks  to  John  Hagerson,  Mike  Thurlkill,  Dennis  Crain,  David  Long,  Ed 
Mills,  Steve  Molstad,  Richard  Herrmann,  Dan  Boone,  and  Kyle  J.  Sparks; 
thanks  also  to  Jeff  Stone,  Dan  Quigley,  Steve  Thompson,  Larry  Israel, 

Teresa  Posakony,  Neil  Sandlin,  Curt  Palmer,  David  Flenniken,  Charles  E. 

Kindel  Jr.,  and  Doug  Laundry. 

■  To  everyone  at  Microsoft  Press  who  has  been  involved  in  the  first,  second, 
and  third  editions  of  PROGRAMMING  WINDOWS,  for  behind-the-scenes 
work  that  makes  all  the  difference  in  the  world. 

■  To  my  friends  and  editors  at  PC  Magazine  and  Microsoft  Systems  Journal , 
for  their  help  and  encouragement  over  the  years. 

■  To  my  family — my  Mom;  my  brother  Steve  and  his  wife  Bernie  and  their 
children  Christopher  and  Michelle;  my  sister  Sue  and  her  husband  Rich 
and  their  daughters  Erika  and  Alyssa. 

■  To  my  friends  who  know  nothing  about  computers,  for  helping  me  keep 
my  sanity,  and  to  my  pool-shooting  buddies  at  Finian’s  Rainbow,  for  some 
late-night  nonprogramming  insanity.  Rack  ’em  up  and  let’s  break. 


Charles  Petzold 
July  4,  1992 
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USING  THE  COMPANION  DISK 

Bound  into  the  back  of  this  book  is  a  3.5-inch,  1.44-megabyte  companion  disk 
containing  the  source  code  and  executable  (EXE)  files  for  all  the  sample  pro¬ 
grams  described  in  the  third  edition  of  PROGRAMMING  WINDOWS  by  Charles 
Petzold  (Microsoft  Press,  1992).  The  programs  are  stored  in  subdirectories  corre¬ 
sponding  to  the  book  chapters. 

Installing  the  Disk 

To  copy  these  programs  to  your  hard  disk,  use  the  XCOPY  command. 

1.  Create  a  subdirectory  on  your  hard  disk: 

MD  \ PROGW I N 

2.  Change  to  that  subdirectory: 

CD  \PR0GWIN 

To  copy  the  entire  companion  disk  to  your  hard  disk,  put  the  companion 
disk  in  drive  A  and  then  execute: 

XCOPY  A: \*.*  /S 

To  copy  an  individual  directory  (Chapter  10,  for  example)  from  the  compan¬ 
ion  disk  to  your  hard  disk,  follow  steps  1  and  2  above  and  then  execute: 

XCOPY  A:\CHAP10  .\CHAP10\*.*  /S 

Exploring  the  Disk 

In  the  root  directory  of  the  companion  disk  (or  the  \PROGWIN  directory  on  your 
hard  disk  if  you  followed  the  steps  above),  you’ll  find  four  batch  files  named 
MSC.BAT,  BCP.BAT,  MSCDLL.BAT,  and  BCPDLL.BAT. 

Before  compiling  the  programs,  you  must  first  execute  MSC.BAT  and 
MSCDLL.BAT  if  you’re  using  Microsoft  C/C++  7.0,  or  BCP.BAT  and  BCPDLL.BAT  if 
you’re  using  Borland  C++  3.1. 

If  you  want  to  re-create  all  the  EXE  files,  you  can  run  the  MAKEMSC.BAT 
batch  file  for  the  Microsoft  compiler  or  the  MAKEBCP.BAT  batch  file  for  the 
Borland  compiler. 
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CHAPTER  1 


Hello, 

Windows 


Since  its  introduction  in  November  1985,  Microsoft  Windows  has  emerged  as  the  most 
popular  graphical  user  interface  environment  for  MS-DOS.  Over  10  million  copies  of  Win¬ 
dows  have  been  shipped,  and  hundreds  of  Windows  applications  are  currently  available. 

For  the  user,  Windows  provides  a  multitasking,  graphical-based  windowing  environ¬ 
ment  that  runs  programs  especially  designed  for  Windows.  Such  programs  include 
Microsoft  Excel  (spreadsheet  and  business  graphics),  Microsoft  Word  for  Windows  (word 
processing),  Aldus’s  PageMaker  (desktop  publishing),  Samna’s  Ami  (word  processing), 
Micrografx’s  Designer  (drawing),  IBM’s  Current  (a  personal  information  manager), 
Asymetrix’s  ToolBook  (a  software  construction  kit),  and  many  others.  Programs  written  for 
Windows  have  a  consistent  appearance  and  command  structure  and  are  thus  often  easier 
to  learn  and  use  than  conventional  MS-DOS  programs.  Users  can  easily  switch  among  dif¬ 
ferent  Windows  programs  and  exchange  data  between  them.  Windows  also  provides  an 
easy-to-use,  icon-based  Program  Manager  for  running  programs,  as  well  as  a  File  Manager 
and  Print  Manager  for  file  maintenance  and  printer-queue  management. 

Although  Windows  exists  primarily  to  run  applications  especially  written  for  the  en¬ 
vironment,  Windows  can  also  run  many  programs  written  for  MS-DOS.  Of  course,  these 
programs  cannot  take  advantage  of  many  Windows  features,  but  in  some  cases  they  can  be 
windowed  and  multitasked  alongside  Windows  programs. 

For  the  program  developer,  Windows  provides  a  wealth  of  built-in  routines  that  allow 
the  use  of  menus,  dialog  boxes,  scroll  bars,  and  other  components  of  a  friendly  user  inter¬ 
face.  Windows  also  contains  an  extensive  graphics  programming  language  that  includes 
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the  use  of  formatted  text  in  a  variety  of  fonts.  Programmers  can  treat  the  keyboard,  mouse, 
video  display,  printer,  system  timer,  and  RS-232  communication  ports  in  a  device¬ 
independent  manner.  Windows  programs  run  the  same  on  a  variety  of  hardware 
configurations. 

A  BRIEF  HISTORY  OF  WINDOWS 

Windows  was  announced  by  Microsoft  Corporation  in  November  1983  and  was  released  2 
years  later  in  November  1985.  Over  the  next  2  years,  Microsoft  Windows  1.01  (the  first 
released  version)  was  followed  by  several  updates  to  support  the  international  market  and 
to  provide  drivers  for  additional  video  displays  and  printers. 

Windows  2.0  was  released  in  November  1987.  This  version  incorporated  several 
changes  to  the  user  interface.  The  most  significant  of  these  changes  involved  the  use  of 
overlapping  windows  rather  than  the  “tiled”  windows  found  in  the  earlier  versions  of 
Windows.  Windows  2.0  also  included  enhancements  to  the  keyboard  and  mouse  interface, 
particularly  for  menus  and  dialog  boxes. 

Windows/386  (released  shortly  after  Windows  2.0)  used  the  “virtual  86”  mode  of  the 
80386  microprocessor  to  window  and  multitask  many  DOS  programs  that  directly  access 
hardware.  For  symmetry,  Windows  2.1  was  renamed  Windows/286. 

Windows  3.0  was  introduced  in  a  spectacular  product  announcement  on  May  22, 
1990.  The  earlier  Windows/286  and  Windows/386  versions  were  merged  into  one  product 
with  this  release.  The  big  change  in  Windows  3  was  the  support  of  the  protected  mode 
operation  of  Intel’s  80286,  80386,  and  80486  microprocessors.  This  gave  Windows  and 
Windows  applications  access  to  up  to  16  megabytes  (MB)  of  memory.  The  Windows  “shell” 
programs  (the  Program  Manager,  Task  Manager,  and  File  Manager)  were  completely 
revamped. 

Microsoft  Windows  version  3-1 — the  subject  of  this  book — was  released  in  April 
1992.  The  most  significant  new  feature  in  Windows  3.1  is  the  TrueType  font  technology  de¬ 
veloped  by  Apple  Computer,  Inc.,  and  Microsoft.  TrueType  brings  scalable  outline  fonts  to 
Windows.  Also  included  in  Windows  3.1  is  support  for  Multimedia  (sound  and  music), 
Object  Linking  and  Embedding  (OLE),  and  for  common  dialog  boxes.  Windows  3.1  runs 
only  in  protected  mode  and  requires  an  80286  or  80386  processor  with  at  least  1  MB  of 
memory. 

Windows  now  forms  the  center  of  Microsoft’s  strategy  for  operating  systems. 
Microsoft  has  targeted  Windows  for  everything  from  small,  hand-held,  stylus-based 
machines  to  powerful  RISC  (reduced  instruction  set  computing)  workstations.  Multimedia 
extensions  to  Windows  give  programs  access  to  sound  and  music  hardware.  For  the  future, 
Microsoft  is  working  on  a  version  of  Windows  that  incorporates  full  support  for  a  32-bit 
flat  address  space  and  32-bit  instructions.  There  will  be  a  32-bit  Windows  for  MS-DOS 
machines  running  with  an  Intel  80386  or  80486  microprocessor  and  a  portable  version 
(currently  dubbed  “NT”  for  “new  technology”)  running  on  RISC-based  workstations. 
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THE  USER’S  PERSPECTIVE 

Windows  provides  considerable  advantages  to  both  users  and  programmers  over  the  con¬ 
ventional  MS-DOS  environment.  The  benefits  to  users  and  the  benefits  to  program  devel¬ 
opers  are  really  quite  similar  because  the  job  of  a  program  developer  is  to  give  users  what 
they  need  and  want.  Windows  makes  this  possible. 

The  Graphical  User  Interface  (GUI) 

Windows  is  a  graphical  user  interface  (GUI),  sometimes  also  called  a  “visual  interface”  or 
“graphical  windowing  environment.”  The  concepts  behind  this  type  of  user  interface  date 
from  the  mid-1970s,  with  the  pioneering  work  done  at  the  Xerox  Palo  Alto  Research  Center 
(PARC)  for  machines  such  as  the  Alto  and  the  Star  and  for  environments  such  as  SmallTalk. 

The  work  done  at  Xerox  PARC  was  brought  into  the  mainstream  and  popularized  by 
Apple  Computer,  Inc.,  first  in  the  ill-fated  Lisa  and  then  a  year  later  in  the  much  more  suc¬ 
cessful  Macintosh,  introduced  in  January  1984.  The  Apple  Macintosh  remains  a  significant 
challenger  to  IBM’s  dominance  in  the  personal-computer  business  market.  It  is  not  so 
much  the  hardware  of  the  Macintosh  but  its  operating  system  that  makes  the  machine 
so  appealing  to  users.  The  Mac  is  simply  easier  to  use  and  learn  than  an  IBM  PC  running 
MS-DOS. 

Since  the  introduction  of  the  Macintosh,  graphical  user  interfaces  have  bloomed  like 
wildflowers  throughout  the  personal-computer  industry  and  the  not-so-personal  com¬ 
puter  industry  as  well.  For  IBM-compatibles  running  MS-DOS,  there  is  Windows.  For  IBM- 
compatibles  running  OS/2,  there  is  the  Presentation  Manager.  For  the  Commodore  Amiga, 
there  is  Intuition.  For  the  Atari,  there  is  GEM.  For  machines  running  UNIX,  there  is  the 
X-Window  system.  For  Sun  Microsystems  workstations,  there  is  NeWS.  For  the  NeXT,  there 
is  NextStep. 

It  is  obvious  that  the  graphical  user  interface  is  now  (in  the  words  of  Microsoft’s 
Charles  Simonyi)  the  single  most  important  “grand  consensus”  of  the  personal-computer 
industry.  Although  the  various  graphical  environments  differ  in  details,  they  have  similar 
characteristics. 

GUI  Concepts  and  Rationale 

All  graphical  user  interfaces  make  use  of  graphics  on  a  bitmapped  video  display.  Graphics 
provides  better  utilization  of  screen  real  estate,  a  visually  rich  environment  for  conveying 
information,  and  the  possibility  of  a  WYSIWYG  (what  you  see  is  what  you  get)  video  dis¬ 
play  of  graphics  and  formatted  text  prepared  for  a  printed  document. 

In  earlier  days,  the  video  display  was  used  solely  to  echo  text  that  the  user  typed 
using  the  keyboard.  In  a  graphical  user  interface,  the  video  display  itself  becomes  a  source 
of  user  input.  The  video  display  shows  various  graphical  objects  in  the  form  of  icons  and 
input  devices  such  as  buttons  and  scroll  bars.  Using  the  keyboard  (or,  more  directly,  a 
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pointing  device  such  as  a  mouse),  the  user  can  directly  manipulate  these  objects  on  the 
screen.  Graphics  objects  can  be  dragged,  buttons  can  be  pushed,  and  scroll  bars  can  be 
scrolled. 

The  interaction  between  the  user  and  a  program  thus  becomes  more  intimate.  Rather 
than  the  one-way  cycle  of  information  from  the  keyboard  to  the  program  to  the  video  dis¬ 
play,  the  user  directly  interacts  with  the  objects  on  the  display. 

The  Consistent  User  Interface 

Users  no  longer  expect  to  spend  long  periods  of  time  learning  how  to  use  the  computer  or 
mastering  a  new  program.  Windows  helps  because  all  Windows  programs  have  the  same 
fundamental  look  and  feel.  The  program  occupies  a  window — a  rectangular  area  on  the 
screen.  It  is  identified  by  a  caption  bar.  Most  program  functions  are  initiated  through  the 
program’s  menu.  Figure  1-1  shows  a  typical  Windows  program  (in  this  case  WRITE,  the 
word  processor  included  in  Windows)  with  the  various  window  components  labeled. 

Some  menu  items  invoke  dialog  boxes,  in  which  the  user  enters  additional  informa¬ 
tion.  One  dialog  box  found  in  almost  every  large  Windows  program  opens  a  file.  (See 
Figure  1-2.)  This  dialog  box  looks  the  same  (or  very  similar)  in  many  different  Windows 
programs,  and  it  is  almost  always  invoked  from  the  same  menu  option. 


System 
menu  box 


Caption  bar 
(or  title  bar) 


Menu 

bar 


Minimize 

box 


Write  -  ISHMAEL.WRI 


File  Edit  Find  Character  Paragraph  Document  Help 


Call  me  Ishmael.  Some  years  ago  —  never  mind  how  long  precisely  —  having 
little  or  no  money  in  my  purse,  and  nothing  particular  to  interest  me  on 
shore,  I  thought  I  would  sail  about  a  little  and  see  the  watery  part  of  the 
world.  It  is  a  way  I  have  of  driving  off  the  spleen,  and  regulating  the 
circulation.  Whenever  I  find  myself  growing  grim  about  the  mouth; 
whenever  it  is  a  damp,  drizzly  November  in  my  soul;  whenever  I  find  myself 
involuntarily  pausing  before  coflin  warehouses,  and  bringing  up  the  rear  of 
every  funeral  I  meet;  and  especially  whenever  my  hypos  get  such  an  upper 
hand  of  me,  that  it  requires  a  strong  moral  principle  to  prevent  me  from 
deliberately  stepping  into  the  street,  and  methodically  knocking  people's  hats 
off  —  then,  I  account  it  high  time  to  get  to  sea  as  soon  as  I  can.  This  is  my  — 
substitute  for  pistol  and  ball.  With  a  philosophical  flourish  Cato  throws 
himself  upon  his  sword;  I  quietly  take  to  the  ship.  There  is  nothing  surprising 
in  this.  If  they  but  knew  it,  almost  all  men  in  their  degree,  some  time  or 
other,  cherish  very  nearly  the  same  feelings  tow*ards  the  ocean  with  me. 
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Figure  1-1.  WRITE,  a  typical  Windows  program . 
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Figure  1-2.  A  dialog  box  to  open  a  file. 

Once  you  know  how  to  use  one  Windows  program,  you’re  in  a  good  position  to 
easily  learn  another.  The  menus  and  dialog  boxes  allow  a  user  to  experiment  with  a  new 
program  and  explore  its  features.  Most  Windows  programs  have  both  a  keyboard  interface 
and  a  mouse  interface.  Although  most  functions  of  Windows  programs  can  be  controlled 
through  the  keyboard,  using  the  mouse  is  often  easier  for  many  chores; 

From  the  programmer’s  perspective,  the  consistent  user  interface  results  from  using 
the  routines  built  into  Windows  for  constructing  menus  and  dialog  boxes.  All  menus  have 
the  same  keyboard  and  mouse  interface  because  Windows,  rather  than  the  application 
program,  handles  this  job. 

The  Multitasking  Advantage 

Although  some  people  continue  to  question  whether  multitasking  is  really  necessary  on  a 
single-user  computer,  users  definitely  are  ready  for  multitasking  and  can  benefit  from  it. 
The  popularity  of  MS-DOS  RAM-resident  programs  such  as  Sidekick  proves  it.  Although 
popups  are  not,  strictly  speaking,  multitasking  programs,  they  do  allow  fast  context 
switching.  This  involves  many  of  the  same  concepts  as  multitasking. 

Under  Windows,  every  program  in  effect  becomes  a  RAM-resident  popup.  Several 
Windows  programs  can  be  displayed  and  running  at  the  same  time.  Each  program  oc¬ 
cupies  a  rectangular  window  on  the  screen,  as  shown  in  Figure  1-3  on  the  following  page. 
The  user  can  move  the  windows  around  on  the  screen,  change  their  size,  switch  between 
different  programs,  and  transfer  data  from  one  program  to  another.  Because  this  display 
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Write  -  ISH.WRI 


File  Edit  Find  Character  Paragraph  Document  Help 


Call  me  Ishmael.  Some  years  ago  —  never  mind  how  long  precisely  — 
having  little  or  no  money  in  my  purse,  and  nothing  particular  to 
interest  me  on  shore,  I  thought  I  would  sail  about  a  little  and  see  the 
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Figure  1-3.  Several  programs  running  under  Windows. 

looks  something  like  a  desktop  (in  the  days  before  the  desk  became  dominated  by  the 
computer  itself,  of  course),  Windows  is  sometimes  said  to  use  a  “desktop  metaphor”  for 
the  display  of  multiple  programs. 

Memory  Management 

An  operating  system  cannot  implement  multitasking  without  doing  something  about 
memory  management.  As  new  programs  are  started  up  and  old  ones  terminate,  memory 
can  become  fragmented.  The  system  must  be  able  to  consolidate  free  memory  space.  This 
requires  the  system  to  move  blocks  of  code  and  data  in  memory. 

Even  Windows  1,  running  on  an  8088  microprocessor,  was  able  to  perform  this  type 
of  memory  management.  Under  real  mode,  this  can  only  be  regarded  as  an  astonishing  feat 
of  software  engineering.  Programs  running  under  Windows  can  overcommit  memory;  a 
program  can  contain  more  code  than  can  fit  into  memory  at  any  one  time.  Windows  can 
discard  code  from  memory  and  later  reload  the  code  from  the  program’s  .EXE  file.  A  user 
can  run  several  copies  (called  “instances”)  of  a  program;  all  these  instances  share  the  same 
code  in  memory.  Programs  running  in  Windows  can  share  routines  located  in  other  .EXE 
files  called  “dynamic  link  libraries.”  Windows  includes  a  mechanism  to  link  the  program 
with  the  routines  in  the  dynamic  link  libraries  at  run  time.  Windows  itself  is  a  set  of 
dynamic  link  libraries. 
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Thus,  even  in  Windows  1,  the  640-kilobyte  (KB)  memory  limit  of  the  PC’s  architec¬ 
ture  was  effectively  stretched  without  requiring  any  additional  memory.  But  Microsoft 
didn’t  stop  there:  Windows  2  gave  the  Windows  applications  access  to  expanded  memory 
(EMS),  and  Windows  3  runs  in  protected  mode  to  give  Windows  applications  access  to  up 
to  16  MB  of  extended  memory. 

The  Device-Independent  Graphics  Interface 

Windows  is  a  graphical  interface,  and  Windows  programs  can  make  full  use  of  graphics 
and  formatted  text  on  both  the  video  display  and  the  printer.  A  graphical  interface  is  not 
only  more  attractive  in  appearance,  but  it  can  also  impart  a  high  level  of  information  to  the 
user,  as  you  can  see  in  Figure  1-4. 

Programs  written  for  Windows  do  not  directly  access  the  hardware  of  graphics  dis¬ 
play  devices  such  as  the  screen  and  printer.  Instead,  Windows  includes  a  graphics  pro¬ 
gramming  language  (called  the  Graphics  Device  Interface,  or  GDI)  that  allows  the  easy 
display  of  graphics  and  formatted  text.  Windows  virtualizes  display  hardware.  A  program 
written  for  Windows  will  run  with  any  video  board  or  any  printer  for  which  a  Windows  de¬ 
vice  driver  is  available.  The  program  does  not  need  to  determine  what  type  of  device  is 
attached  to  the  system. 


Figure  1-4.  Microsoft  Excel  running  under  Windows. 
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Putting  a  device-independent  graphics  interface  on  the  IBM  PC  was  not  an  easy  job 
for  the  developers  of  Windows.  The  PC  design  was  based  on  the  principle  of  open  archi¬ 
tecture.  Third-party  hardware  manufacturers  were  encouraged  to  develop  peripherals  for 
the  PC  and  have  done  so  in  great  number.  Although  several  standards  have  emerged,  con¬ 
ventional  MS-DOS  programs  for  the  PC  must  individually  support  many  different  hardware 
configurations.  For  example,  it  is  fairly  common  for  an  MS-DOS  word-processing  program 
to  be  sold  with  one  or  two  disks  of  small  files,  each  one  supporting  a  particular  printer. 

Windows  programs  do  not  require  these  drivers  because  the  support  is  part  of  Win¬ 
dows.  This  benefits  users  because  most  Windows  programs  require  very  little  in  the 
way  of  installation.  In  some  cases,  everything  a  program  needs  can  be  included  in  the 
program’s  single  .EXE  file.  The  user  can  often  copy  the  .EXE  file  to  the  fixed  disk,  load 
Windows,  and  go. 

MS-DOS  Applications 

Although  Windows  primarily  exists  to  run  new  programs  specifically  designed  for  the  en¬ 
vironment,  Windows  can  also  run  many  non-Windows  MS-DOS  programs.  The  Windows 
User’s  Guide  refers  to  these  as  “standard  applications,”  but  many  Windows  programmers 
call  them  “old  applications”  or  “old  apps.” 

These  MS-DOS  programs  can  be  divided  into  two  broad  categories.  Well-behaved 
applications  (or  “good  old  apps”)  are  those  that  use  the  MS-DOS  and  PC  ROM  BIOS  (basic 
input/output  system)  software  interrupts  to  read  the  keyboard  and  write  to  the  video  dis¬ 
play.  These  programs  can  generally  run  in  a  window. 

“Bad  apps”  are  those  that  write  directly  to  the  video  display,  use  graphics,  or  take 
control  of  the  hardware  keyboard  interrupt.  The  term  “bad”  here  refers  not  to  the  quality  of 
the  program — many  of  the  best  programs  written  for  the  PC  are  bad  apps  when  it  comes  to 
Windows — but  to  the  way  in  which  the  program  uses  the  hardware  of  the  PC.  When  run¬ 
ning  on  a  286-based  machine,  there  is  simply  no  way  Windows  can  allow  such  a  program 
to  be  windowed  or  multitasked.  However,  Windows  can  use  the  virtual  86  mode  of  the  386 
microprocessor  to  window  and  multitask  even  bad  applications. 


THE  PROGRAMMER’S  PERSPECTIVE 

Windows  has  the  reputation  of  being  easy  for  users  but  difficult  for  programmers.  If  you 
have  no  prior  experience  with  programming  for  a  graphical  user  interface,  you  should  be 
warned  right  now  that  you  will  encounter  some  very  strange  concepts.  Almost  every 
programmer  who  begins  writing  code  for  Windows  must  go  through  some  mental  reorien¬ 
tation  to  assimilate  these  concepts. 

If  at  first  you  find  Windows  programming  to  be  difficult,  awkward,  bizarrely  con¬ 
voluted,  and  filled  with  alien  concepts,  rest  assured  that  this  is  a  normal  reaction.  You  are 
not  alone. 
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Windows  and  MS-DOS 

You  start  up  Windows  as  if  it  were  a  normal  application  program  running  under  MS-DOS. 
But  as  Windows  loads,  it  becomes  almost  a  full-fledged  operating  system.  It’s  not  quite  an 
operating  system  because  it  runs  on  top  of  MS-DOS.  While  Windows  is  running,  it  shares 
responsibility  with  MS-DOS  for  managing  the  hardware  resources  of  the  computer. 
Basically,  MS-DOS  continues  to  manage  the  file  system,  while  Windows  does  everything 
else.  Windows  commands  the  video  display,  keyboard,  mouse,  printer,  and  serial  ports  and 
is  responsible  for  memory  management,  program  execution,  and  scheduling. 

Windows  is  strong  where  MS-DOS  is  weak,  and  weak  where  MS-DOS  is  adequate. 
Windows  includes  almost  no  support  of  file  I/O,  which  is  one  of  the  most  essential  chores 
of  a  minimal  operating  system  such  as  MS-DOS.  This  leads  to  some  amusing — or  not  so 
amusing — consequences.  It  is  easier  in  a  Windows  program  to  create  a  disk-based  metafile 
containing  a  complex  series  of  graphics  drawing  commands  than  to  create  a  simple  ASCII 
text  file.  The  former  is  a  Windows  job;  the  latter  requires  that  the  program  use  MS-DOS. 

The  Windows  Commitment 

Programming  for  Windows  is  an  all-or-nothing  proposition.  For  example,  you  cannot 
write  an  MS-DOS  application — even  a  well-behaved  one — and  use  Windows  only  for 
some  graphics.  If  you  want  to  use  any  part  of  Windows,  you  must  make  the  commitment  to 
write  a  full-fledged  Windows  program. 

The  reason  for  this  will  become  more  obvious  as  you  learn  about  the  structure  of  a 
Windows  program.  Everything  in  Windows  is  interconnected.  If  you  want  to  draw  some 
graphics  on  the  video  display,  you  need  something  called  a  “handle  to  a  device  context.”  To 
get  that,  you  need  a  “handle  to  a  window.”  To  get  that,  you  must  create  a  window  and  be 
prepared  to  receive  “messages”  to  the  window.  To  receive  and  process  messages,  you  need 
a  “window  procedure.”  And  at  that  point  you’re  writing  a  Windows  program.  You  can’t  fly 
unless  you  leave  the  ground. 

The  Function  Calls 

Windows  3.1  supports  over  1000  function  calls  that  applications  can  use.  It  is  highly 
unlikely  that  you  will  ever  memorize  the  syntax  to  all  these  calls.  Most  Windows  program¬ 
mers  keep  the  Windows  Programmer’s  Reference  manual  within  easy  reach. 

Each  of  the  Windows  functions  has  a  descriptive  name  written  in  mixed  uppercase 
and  lowercase  letters,  such  as  CreateWindow.  This  function  (as  you  might  guess)  creates  a 
window  for  your  program.  Another  example:  The  function  IsClipboardFor  mat  Available 
determines  whether  the  clipboard  is  holding  data  of  a  particular  format. 

All  the  main  Windows  functions  are  declared  in  a  header  file  named  WINDOWS.H, 
included  in  the  Windows  Software  Development  Kit  and  the  Borland  C++  Compiler.  WIN¬ 
DOWS.H  is  an  important  part  of  the  Windows  documentation.  You  might  want  to  print  a 
copy  or  use  a  file  browser  for  quick  reference. 
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You  use  these  Windows  functions  in  your  Windows  program  the  same  way  you  use  C 
library  functions  such  as  strlen.  However,  there  are  some  differences  between  the  Win¬ 
dows  functions  and  the  standard  C  library  functions. 

Windows  functions  are  always  declared  a  s  far  pascal  functions.  The  far  keyword  in¬ 
dicates  that  the  Windows  function  is  in  a  different  code  segment  than  the  program’s  code. 
(You’ll  see  the  reason  for  this  shortly.) 

The  pascal  keyword  indicates  that  the  function’s  calling  sequence  is  different  than 
the  normal  C  calling  sequence.  Normally,  the  C  compiler  generates  code  that  pushes  pa¬ 
rameters  on  the  stack  from  right  to  left  beginning  with  the  last  parameter.  The  code  calling 
the  function  is  responsible  for  adjusting  the  stack  pointer  after  the  function  returns.  With 
the  pascal  calling  sequence,  the  parameters  are  pushed  on  the  stack  from  left  to  right  and 
the  called  function  cleans  up  the  stack.  The  pascal  calling  sequence  is  used  in  Windows 
because  it  is  more  efficient. 

With  one  oddball  exception,  any  pointer  passed  to  a  Windows  function  must  be 
a  far  pointer.  This  is  something  you  normally  don’t  have  to  worry  about  because  the 
compiler  will  extend  short  pointers  to  long  pointers  based  on  the  function  template 
in  WINDOWS. H. 

Dynamic  Linking 

If  you’ve  been  working  with  MS-DOS  programming  for  awhile,  you  might  guess  that  a 
Windows  program  interfaces  with  Windows  through  a  software  interrupt  such  as  the 
MS-DOS  Interrupt  0x21.  You  might  guess  that  the  linker  adds  bindings  to  your  Windows 
programs  that  convert  the  Windows  function  calls  into  this  software  interrupt.  But  you 
would  be  wrong.  A  Windows  program  interfaces  to  Windows  through  a  process  called 
“dynamic  linking.” 

Like  MS-DOS  programs,  Windows  executables  have  the  filename  extension  .EXE. 
However,  this  is  not  the  same  .EXE  format  that  is  used  in  MS-DOS.  Instead,  Windows  pro¬ 
grams  use  a  .EXE  format  called  the  New  Executable  file  format.  Whenever  a  Windows 
program  calls  a  Windows  function,  the  C  compiler  generates  assembly-language  code  for  a 
far  call.  A  table  in  the  .EXE  file  identifies  the  function  being  called  using  a  dynamic  link 
library  name  and  either  a  name  or  a  number  (called  the  ordinal  number)  of  the  function 
in  that  library. 

Windows  itself  consists  largely  of  three  dynamic  link  libraries,  called  KRNL286  and 
KRNL386  (responsible  for  memory  management,  loading  and  executing  programs,  and 
scheduling),  USER  (the  user  interface  and  windowing),  and  GDI  (the  graphics).  These  li¬ 
braries  contain  the  code  and  data  for  most  Windows  functions.  You  can  find  these  three 
dynamic  link  libraries  in  the  SYSTEM  subdirectory  of  your  Windows  directory. 

When  a  Windows  program  is  loaded  into  memory,  the  far  calls  in  the  program  are 
resolved  to  point  to  the  entry  of  the  function  in  the  dynamic  link  library,  which  is  also 
loaded  into  memory.  This  is  why  all  Windows  functions  must  be  defined  as  far.  The  code 
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in  the  dynamic  link  libraries  is  not  in  the  same  segment  as  the  program’s  code.  Also,  point¬ 
ers  passed  in  Windows  functions  must  also  be  defined  as  far  to  avoid  confusion  with  the 
dynamic  link  library’s  own  code  and  data  segments. 

Generally,  you  don’t  have  to  worry  about  the  use  of  far  calls  and  far  pointers  because 
the  functions  are  declared  as  far  functions  with  far  pointers  in  WINDOWS.H:  The  C  com¬ 
piler  will  perform  the  necessary  address  translations  for  you. 

When  you  link  a  Windows  program  to  produce  an  executable,  you  must  link  with  a 
special  “import  library”  provided  with  the  Windows  Software  Development  Kit  or  the  Bor¬ 
land  C++  Compiler.  This  import  library  contains  the  dynamic  link  library  names  and  ordi¬ 
nal  numbers  of  all  the  Windows  functions.  The  linker  uses  this  information  to  construct  the 
table  in  the  .EXE  file  that  Windows  uses  to  resolve  calls  to  Windows  functions  when  load¬ 
ing  the  program. 

Object-Oriented  Programming 

When  programming  for  Windows,  you’re  really  engaged  in  a  type  of  object-oriented  pro¬ 
gramming.  This  is  most  evident  in  the  object  you’ll  be  working  with  most  in  Windows — 
the  object  that  gives  Windows  its  name,  the  object  that  will  soon  seem  to  take  on  anthro¬ 
pomorphic  characteristics,  the  object  that  may  even  show  up  in  your  dreams,  the  object 
known  as  the  “window.” 

Windows  are  rectangular  areas  on  the  screen.  A  window  receives  user  input  from  the 
keyboard  or  mouse  and  displays  graphical  output  on  its  surface. 

An  application  window  usually  contains  the  program’s  title  bar,  menu,  sizing  border, 
and  perhaps  some  scroll  bars.  Dialog  boxes  are  additional  windows.  Moreover,  the  surface 
of  a  dialog  box  always  contains  several  additional  windows  called  “child  windows.”  These 
child  windows  take  the  form  of  push  buttons,  radio  buttons,  check  boxes,  text  entry  fields, 
list  boxes,  and  scroll  bars. 

The  user  sees  these  windows  as  objects  on  the  screen  and  interacts  directly  with 
these  objects  by  pushing  a  button  or  scrolling  a  scroll  bar.  Interestingly  enough,  the  pro¬ 
grammer’s  perspective  is  analogous  to  the  user’s  perspective.  The  window  receives  this 
user  input  in  the  form  of  “messages”  to  the  window.  A  window  also  uses  messages  to 
communicate  with  other  windows. 

Understanding  these  messages  is  one  of  the  hurdles  you’ll  have  to  jump  in  becoming 
a  Windows  programmer. 

Message-Driven  Architecture 

The  first  time  I  saw  a  graphical  user  interface  in  action,  I  was  puzzled.  The  demonstration 
included  a  rudimentary  word  processor  running  in  a  window.  The  word  processor  would 
reformat  its  text  when  the  program’s  window  was  resized. 

It  was  obvious  to  me  that  the  operating  system  was  handling  the  details  of  the 
window-resizing  logic  and  that  the  program  was  capable  of  responding  to  this  system 
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function.  How  did  the  program  know  when  its  window  was  resized?  What  was  the  mecha¬ 
nism  the  operating  system  used  to  convey  this  information  to  the  window?  My  previous 
programming  experience  was  useless  in  understanding  how  this  worked. 

It  turns  out  that  the  answer  to  these  questions  is  central  to  understanding  the  archi¬ 
tecture  used  in  graphical  user  interfaces.  In  Windows,  when  a  user  resizes  a  window,  Win¬ 
dows  sends  a  message  to  the  program  indicating  the  new  window  size.  The  program  can 
then  adjust  the  contents  of  its  window  to  reflect  the  new  size. 

“Windows  sends  a  message  to  the  program.”  I  hope  you  didn’t  read  that  statement 
without  blinking.  What  on  earth  could  it  mean?  We’re  talking  about  program  code  here,  not 
an  electronic  mail  system.  How  can  an  operating  system  send  a  message  to  a  program? 

When  I  say  that  “Windows  sends  a  message  to  the  program,”  I  mean  that  Windows 
calls  a  function  within  the  program.  The  parameters  to  this  function  describe  the  partic¬ 
ular  message.  This  function  located  in  your  Windows  program  is  known  as  the  “window 
procedure.” 

The  Window  Procedure 

You  are  undoubtedly  accustomed  to  the  idea  of  a  program  making  calls  to  the  operating 
system.  This  is  how  a  program  opens  a  disk  file,  for  example.  What  you  may  not  be  ac¬ 
customed  to  is  the  idea  of  an  operating  system  making  calls  to  a  program.  Yet  this  is  funda¬ 
mental  to  Windows’  object-oriented  architecture. 

Every  window  that  a  program  creates  has  an  associated  window  procedure.  This 
window  procedure  is  a  function  that  could  be  either  in  the  program  itself  or  in  a  dynamic 
link  library.  Windows  sends  a  message  to  a  window  by  calling  the  window  procedure.  The 
window  procedure  does  some  processing  based  on  the  message  and  then  returns  control 
to  Windows. 

More  precisely,  a  window  is  always  created  based  on  a  “window  class.”  The  window 
class  identifies  the  window  procedure  that  processes  messages  to  the  window.  The  use  of  a 
window  class  allows  multiple  windows  to  be  based  on  the  same  window  class  and  hence 
use  the  same  window  procedure.  For  example,  all  buttons  in  all  Windows  programs  are 
based  on  the  same  window  class.  This  window  class  is  associated  with  a  window  pro¬ 
cedure  (located  in  the  Windows  USER.EXE  dynamic  link  library)  that  processes  messages 
to  all  the  button  windows. 

In  object-oriented  programming,  an  “object”  is  a  combination  of  code  and  data.  A 
window  is  an  object.  The  code  is  the  window  procedure.  The  data  is  information  retained 
by  the  window  procedure  and  information  retained  by  Windows  for  each  window  and 
window  class  that  exists  in  the  system. 

A  window  procedure  processes  messages  to  the  window.  Very  often  these  messages 
inform  a  window  of  user  input  from  the  keyboard  or  mouse.  This  is  how  a  push-button 
window  knows  that  it’s  being  “pressed,”  for  example.  Other  messages  tell  a  window  when 
it  is  being  resized  or  when  the  surface  of  the  window  needs  to  be  repainted. 
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When  a  Windows  program  begins  execution,  Windows  creates  a  “message  queue” 
for  the  program.  This  message  queue  stores  messages  to  all  the  various  windows  a  program 
may  create.  The  program  includes  a  short  chunk  of  code  called  the  “message  loop”  to 
retrieve  these  messages  from  the  queue  and  dispatch  them  to  the  appropriate  window  pro¬ 
cedure.  Other  messages  are  sent  directly  to  the  window  procedure  without  being  placed  in 
the  message  queue. 

If  your  eyes  are  beginning  to  glaze  over  with  this  excessively  abstract  description  of 
Windows  architecture,  maybe  it  will  help  to  see  how  the  window,  the  window  class,  the 
window  procedure,  the  message  queue,  the  message  loop,  and  the  window  messages  all  fit 
together  in  the  context  of  a  real  program. 

YOUR  FIRST  WINDOWS  PROGRAM 

In  their  classic  book  The  C  Programming  Language  (2d  ed.,  Prentice  Hall,  1988),  Brian 
Kernighan  and  Dennis  Ritchie  begin  discussing  C  with  the  now-famous  “Hello,  world” 
program: 

//include  <stdio.h> 

main  () 

{ 

printf  ("Hello,  world\n")  ; 

} 

In  the  remainder  of  this  chapter,  I  will  show  you  the  analogous  program  written  for 
Microsoft  Windows.  The  program  is  called  HELLOWIN,  and  it  creates  a  window  that  dis¬ 
plays  the  text  string  “Hello,  Windows!” 

Lest  you  collapse  from  shock  when  you  first  look  at  the  HELLOWIN  code,  I’ll  warn 
you  now  that  there  are  three  files  involved,  and  that  the  HELLOWIN.C  source  code  file  is 
over  80  lines  long.  Most  of  these  80  lines  are  overhead.  You’ll  have  similar  overhead  in 
almost  every  Windows  program  you  write. 

Rather  than  ask  why  the  “Hello,  Windows”  program  is  so  long  and  complex,  let’s  ask 
why  the  traditional  “Hello,  world”  program  is  so  short  and  simple. 

What’s  Wrong  with  This  Program? 

The  output  model  for  the  “Hello,  world”  program  and  other  traditional  C  programs  is  an 
antique  piece  of  hardware  known  as  the  teletype.  The  teletype  resembles  a  typewriter  with 
a  continuous  roll  of  paper.  In  the  not-too -distant  past,  programmers  would  sit  at  a  teletype 
and  type  in  commands  that  were  echoed  to  the  paper.  The  computer  responded  by  print¬ 
ing  its  output  on  the  paper. 

The  teletype  metaphor  was  extended  to  the  video  display  in  the  early  days  of  com¬ 
puters.  The  video  display  became  a  “glass  teletype”  that  simply  scrolled  when  text  reached 
the  bottom  of  the  screen. 
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How  can  the  traditional  “Hello,  world”  program  display  text  without  telling  the 
operating  system  the  particular  output  device  on  which  the  text  is  to  appear?  Because 
there  is  only  one  output  device — the  video  display  used  as  if  it  were  a  teletype.  If  the  user 
wishes  the  output  to  go  elsewhere,  it  must  be  redirected  from  the  command  line. 

How  can  the  program  display  text  without  telling  the  system  where  on  the  output  de¬ 
vice  the  text  is  to  appear?  Because  the  text  always  appears  where  the  cursor  happens  to  be, 
probably  on  the  next  line  after  you  execute  the  program.  Suppose  you  want  to  display 
“Hello,  world”  in  the  center  of  the  screen.  You’d  have  to  use  some  device-dependent  con¬ 
trol  codes  to  first  position  the  cursor  at  the  desired  location. 

Let’s  say  you  want  to  run  several  “Hello,  world”  programs  at  one  time  and  see  their 
output  on  the  screen.  What  a  mess!  The  copies  of  the  program  would  interfere  with  each 
other.  There  is  nothing  in  the  teletype  metaphor  to  separate  output  from  several  programs 
running  concurrently. 

It’s  also  interesting  that  you  see  the  “Hello,  world”  output  even  after  the  program  ter¬ 
minates.  Rather  than  properly  cleaning  up  after  itself,  the  program  leaves  remnants  of  its 
existence  on  the  video  display. 

The  “Hello,  world”  program  is  so  simple  because  it  is  designed  for  a  simpler  age  and 
simpler  computers  and  simpler  output  devices.  It’s  not  in  the  same  ballpark  as  what  we 
think  of  today  as  modern  software,  and  it’s  not  even  playing  the  same  game. 

The  HELLOWIN  Files 

The  three  files  necessary  to  create  the  “Hello,  Windows”  program  are  shown  in  Figure  1-5: 

■  HELLOWIN.MAK  is  a  “make”  file. 

■  HELLOWIN.C  is  the  C  source  code  file. 

■  HELLOWIN.DEF  is  a  module  definition  file. 

HELLOWIN.MAK 

# . 

#  HELLOWIN.MAK  make  file 

#  . . 

hellowin.exe  :  hellowin.obj  hellowin.def 

$ ( WINLINK)  hellowin,  hellowin,  NUL,  $(WINLIB),  hellowin 
rc  -t  hellowin.exe 

hellowin.obj  :  hellowin.c 
$(WINCC)  hellowin.c 

Figure  1-5.  The  HELLOWIN  program. 
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HELLOWIN.C 

/* .  . 

HELLOWIN.C  -  Displays  "Hello,  Windows!"  in  client  area 
(c)  Charles  Petzold,  1992 

.  . */ 

#include  <windows.h> 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdParam,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "HelloWin"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc  = 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass. hbrBackground  = 
wndclass.lpszMenuName  = 
wndclass. IpszClassName  = 


CS.HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  IDI.APPLICATION)  ; 
LoadCursor  (NULL,  IDC.ARR0W)  ; 
GetStockObject  (WHITE.BRUSH)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName, 

"The  Hello  Program", 

WS.OVERLAPPEDWINDOW, 

CWJJSEDEFAULT, 

CWJJSEDEFAULT, 

CWJJSEDEFAULT, 

CWJJSEDEFAULT, 

NULL, 

NULL, 

hlnstance, 

NULL)  ; 


//  window  class  name 
//  window  caption 
//  window  style 
//  initial  x  position 
//  initial  y  position 
//  initial  x  size 
//  initial  y  size 
//  parent  window  handle 
//  window  menu  handle 
//  program  instance  handle 
//  creation  parameters 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 


(continued) 
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while  (GetMessage  (&msg,  NULL,  0.  0)) 

{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg. wParam  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message, 

UINT  wParam,  LONG  IParam) 


{ 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 
RECT  rect  ; 


switch  (message) 

{ 

case  WM_PA I  NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

GetClientRect  (hwnd,  &rect)  ; 

DrawText  (hdc,  ’’Hello,  Windows!”,  -1,  &rect, 

DT_S INGLELINE  !  DT.C ENTER  !  DT.VCENTER) 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 


case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


HELLOWIN.DEF 


HELLOWIN.DEF  module  definition  file 


NAME  HELLOWIN 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Hello  Windows  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

’WINSTUB.EXE’ 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 
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These  are  standard  files  that  you’ll  create  for  every  Windows  program  you  write.  Generally 
when  you  begin  a  new  Windows  program,  you’ll  copy  the  standard  files  from  an  existing 
program  and  then  make  appropriate  changes  to  them. 

Note:  The  programs  in  this  book  are  provided  on  the  companion  disk.  See  the  sec¬ 
tion  “Using  the  Companion  Disk”  on  page  xviii. 

The  programs  in  this  book  are  designed  to  be  compiled  on  the  MS-DOS  command 
line  using  either  the  Microsoft  C/C++  7.0  Compiler  with  the  Windows  3.1  Software  Devel¬ 
opment  Kit,  or  the  Borland  C++  3.1  Compiler.  The  make  files  use  MS-DOS  environment 
variables  for  the  names  and  command-line  options  of  the  two  compilers  and  linkers. 

If  you’re  using  the  Microsoft  tools,  run  the  batch  file  shown  in  Figure  1-6  or  add  the 
batch  file’s  lines  to  your  AUTOEXEC.BAT  file.  To  create  HELLOWIN.EXE  from  the  three 
files  shown  in  Figure  1-5,  run: 

NMAKE  HELLOWIN.MAK 

on  the  MS-DOS  command  line.  If  you’re  using  the  Borland  compiler,  run  the  batch  file 
shown  in  Figure  1-7  or  add  the  batch  file’s  lines  to  your  AUTOEXEC.BAT  file.  To  create 
HELLOWIN.EXE,  run: 

MAKE  -f  HELLOWIN.MAK 

Notice  the  dash  (-)  and  lowercase  “f”  preceding  the  make  file  name. 

MSC.BAT 

REM  .  . 

REM  MSC.BAT  -  Set  up  environment  for  Microsoft  C/C++  7.0  NMAKE 

REM  . 

SET  WINCC=cl  -c  -G2sw  -Ow  -W3  -Zp  -Tp 
SET  WINLINK=1 ink  /nod 

SET  WINLIB=slibcew  oldnames  libw  commdlg  ddeml 
SET  WINRC=rc  -r 

Figure  1  -6.  The  MSC.BAT file  for  using  the  Microsoft  Windows  3 ■  7  Software  Development  Kit  and 
the  Microsoft  C/C++  7.0  Compiler. 


BCP.BAT 

REM  .  .  . 

REM  BCP.BAT  -  Set  up  environment  for  Borland  C++  3.1  MAKE 

REM  .  .  -  . 

SET  WINCC=bcc  -c  -w-par  -P  -W  -2 
SET  WINLINK=tlink  /c  /n  /Tw  /L\borl andc\l ib  c0ws 
SET  WINLIB=c  import  mathws  cws 
SET  WINRC=rc  -r  -i\borlandc\include 


Figure  1  -7.  The  BCP.BAT file  for  using  the  Borland  C++  3-1  Compiler. 
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You  can  also  use  the  Programmer’s  Workbench  included  in  Microsoft  C/C++  7.0  for 
compiling  the  programs  in  this  book.  When  you  load  in  the  make  file  using  the  Set  Pro¬ 
gram  List  command  from  the  Make  menu  option,  specify  that  HELLOWIN.MAK  is  a  “non- 
PWB  Makefile.”  You  can  also  use  the  Borland  Programmer’s  Platform  or  the  Microsoft 
QuickC  or  the  Borland  Turbo  C++  environments  by  creating  a  project  file  for  the  program. 

If  you  compile  outside  of  Windows,  after  creating  HELLOWIN.EXE,  you  can  then  run 
Windows  and  the  program  by  executing: 

WIN  HELLOWIN 

Or,  if  you  compile  inside  Windows,  you  can  then  run  the  program  from  the  Program 
Manager.  The  program  creates  a  normal  application  window  as  shown  in  Figure  1-8.  The 
window  displays  “Hello,  Windows!”  in  the  center  of  its  client  area. 

When  you  think  about  it,  this  window  has  an  amazing  amount  of  functionality  in  its 
mere  80  lines  of  code.  You  can  grab  the  title  bar  with  the  mouse  pointer  and  move  the  win¬ 
dow  around  the  screen.  You  can  grab  the  sizing  borders  and  resize  the  window.  When  the 
window  changes  size,  the  program  will  automatically  reposition  the  “Hello,  Windows!” 
text  string  in  the  new  center  of  the  client  area.  You  can  press  the  maximize  button  and 
zoom  HELLOWIN  to  fill  the  screen.  You  can  press  the  minimize  button  and  compress  the 
program  into  an  icon.  You  can  invoke  all  these  options  from  the  system  menu  and,  in 
addition,  close  the  window  to  terminate  the  program. 


The  Hello  Program  BB! 


Figure  1-8.  HELLOWIN  running  under  Windows. 
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While  you  may  be  pleased  to  see  that  HELLOWIN  has  all  the  functionality  of  a  nor¬ 
mal  Windows  program,  you  may  not  look  so  pleasant-faced  when  you  examine  the  source 
code  required  to  create  this  program.  But  let’s  be  brave  while  I  proceed  to  dissect  this  pro¬ 
gram  piece  by  piece  and  analyze  it  to  death. 

The  Make  File 

To  ease  compilation  of  Windows  programs,  you  can  use  the  NMAKE  utility  included  with 
Microsoft  C/C++  7.0  or  the  MAKE  utility  included  with  Borland  C++  3.1.  Whenever  you 
change  something  in  one  of  the  HELLOWIN  source  files,  all  you  need  do  is  run  NMAKE  or 
MAKE  as  shown  above  to  create  the  updated  HELLOWIN.EXE  executable. 

A  make  file  consists  of  one  or  more  sections,  each  of  which  begins  with  a  left- 
justified  line  that  lists  a  target  file,  followed  by  a  colon,  followed  by  one  or  more  dependent 
files.  This  line  is  followed  by  one  or  more  indented  command  lines.  These  commands 
create  the  target  file  from  the  dependent  files.  If  the  last  modification  date  and  time  of  any 
of  the  dependent  files  is  later  than  the  last  modification  date  and  time  of  the  target  file,  then 
NMAKE  or  MAKE  executes  the  indented  command  lines. 

Normally,  NMAKE  or  MAKE  will  update  only  the  target  file  in  the  first  section  of  the 
make  file.  However,  if  one  of  the  dependent  files  is  itself  a  target  file  in  another  section  of 
the  make  file,  then  NMAKE  or  MAKE  will  update  that  target  first. 

The  HELLOWIN.MAK  make  file  contains  two  sections.  The  first  section  runs  the 
linker  if  either  HELLOWIN.OBJ  or  HELLOWIN.DEF  has  been  altered  more  recently  than 
HELLOWIN.EXE: 

hellowin.exe  :  hellowin.obj  hellowin.def 

$(WINLINK)  hellowin,  hellowin,  NUL,  $(WINLIB),  hellowin 
rc  hellowin.exe 

The  second  section  runs  the  C  compiler  if  HELLOWIN.C  has  been  changed  more  re¬ 
cently  than  HELLOWIN.OBJ: 

hellowin.obj  :  hellowin.c 
$ ( W I NCC )  hellowin.c 

The  WINLINK,  WINLIB,  and  WINCC  keywords  are  macro  identifiers  obtained  from 
the  MS-DOS  environment  set  up  with  MSC.BAT  or  BCP.BAT. 

Because  HELLOWIN.OBJ  is  a  dependent  file  in  the  first  section  of  the  make  file  and  a 
target  file  in  the  second  section,  NMAKE  or  MAKE  will  check  whether  HELLOWIN.OBJ 
needs  updating  before  re-creating  HELLOWIN.EXE.  Thus,  the  make  file  should  be 
analyzed  from  the  bottom  up. 

Running  the  C  compiler  creates  the  HELLOWIN.OBJ  object  module  from  the 
HELLOWIN.C  source  code  file.  If  you’re  using  the  Microsoft  compiler,  the  command  line 
for  running  the  CL.EXE  compiler  is: 

cl  -c  -G2sw  -Ow  -W3  -Zp  -Tp  hellowin.c 
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Several  compiler  switches  are  required  (or  recommended)  for  compiling  Windows 
programs: 

■  The  -c  switch  indicates  that  the  program  should  be  compiled  only  and  not 
yet  linked.  The  link  is  a  separate  step. 

■  The  -G2sw  switch  is  actually  three  switches:  -G2,  -Gs,  and  -Gw.  The  -G2 
switch  causes  the  compiler  to  generate  286  code.  The  -Gs  switch  disables 
checks  for  stack  overflow.  Because  stack  overflow  messages  are  written 
to  standard  error  output  (and  are  hence  ignored  by  Windows),  it’s  best 
simply  to  be  sure  that  you  are  using  a  sufficient  stack.  (Four  kilobytes 
is  recommended.) 

■  The  -Gw  switch  is  a  special  Windows  switch  that  inserts  special  prolog 
and  epilog  code  in  all  far  functions  in  the  program.  This  code  (which  I’ll 
discuss  in  Chapter  7)  aids  Windows  in  moving  code  and  data  segments  in 
memory. 

■  The  -Ow  switch  concerns  optimization.  With  this  switch  the  compiler 
will  avoid  some  optimizations  that  may  cause  problems  specifically  with 
Windows  programs. 

■  The  -W3  switch  enables  warning  level  3  for  displaying  warning  messages. 

You  should  make  an  effort  to  write  programs  that  show  no  warning 
messages  when  you  compile  with  this  switch.  Windows  will  not  tolerate 
sloppy  programming,  which  can  lead  to  nasty  bugs. 

■  The  -Zp  switch  packs  structure  fields  on  byte  boundaries.  This  is 
required  for  some  of  the  structures  defined  in  WINDOWS.H  that 
programs  use  to  communicate  with  Windows.  Windows  assumes  that  all 
structures  are  packed. 

■  The  -Tp  switch  compiles  the  program  in  C++  mode.  Because  C 
compilation  and  C++  compilation  are  a  little  different  and  can  involve 
different  errors  and  warning  messages,  compiling  with  this  switch 
initially  can  help  if  you  later  add  C++  extensions  to  your  Windows  code. 

If  you’re  using  the  Borland  compiler,  the  command  line  to  run  the  BCC.EXE  com¬ 
piler  is: 

bcc  -c  -w-par  -P  -2  -W  hellowin.c 

Here  are  the  Borland  compiler  switches  used  for  compiling  Windows  programs: 

■  The  -c  switch  indicates  that  the  program  should  be  compiled  only  and  not 
yet  linked. 
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■  The  -w-par  switch  inhibits  warning  messages  that  indicate  when  func¬ 
tion  parameters  are  not  used.  This  is  sometimes  the  case  in  Windows 
programs. 

■  The  -P  switch  compiles  the  program  in  C++  mode. 

■  The  -W  switch  is  the  special  Windows  compilation  switch. 

■  The  -2  switch  generates  286  code. 

The  first  section  of  the  make  file  runs  two  commands  if  HELLOWIN.OBJ  or 
HELLOWIN.DEF  has  been  altered  more  recently  than  HELLOWIN.EXE.  If  you’re  using  the 
Microsoft  compiler,  the  first  indented  command  runs  the  LINK.EXE  linker: 

link  /nod  hellowin,  hellowin,  \ 

NUL,  slibcew  oldnames  libw  commdlg  ddeml,  hellowin 

The  first  field  indicates  the  HELLOWIN.OBJ  object  file.  The  .OBJ  extension  is 
assumed.  The  second  field  lists  the  name  of  the  executable  file,  HELLOWIN.EXE.  The 
third  field  is  the  name  of  an  optional  map  file.  This  is  set  to  NUL  to  create  no  map  file. 

The  fourth  field  lists  the  libraries.  SLIBCEW.LIB  is  the  small  model  Windows  C  run 
time  library  created  during  installation  of  Microsoft  C/C++  7.0.  OLDNAMES.LIB  allows  the 
use  of  traditional  names  of  non-ANSI  C  library  functions,  and  LIBW.LIB  is  an  import  library 
from  the  Windows  3.1  Software  Development  Kit  that  contains  information  LINK  uses  to 
set  up  a  table  in  the  .EXE  file  so  that  Windows  can  dynamically  link  the  program’s  calls  to 
Windows  functions  with  the  Windows  dynamic  link  libraries  that  contain  those  functions. 
COMMDLG. LIB  is  the  import  library  for  the  common  dialog  box  library  (discussed  in 
Chapter  10).  The  /nod  switch  at  the  beginning  of  the  command  line  tells  the  compiler  to 
use  these  three  libraries  without  performing  a  default  library  search. 

The  fifth  field  indicates  the  name  of  the  program’s  module  definition  file, 
HELLOWIN.DEF.  The  .DEF  extension  is  assumed.  (I’ll  discuss  this  file  later  in  this  chapter.) 
It  contains  information  that  LINK  uses  to  construct  HELLOWIN.EXE. 

If  you’re  using  the  Borland  compiler,  the  first  indented  command  runs  the 
TLINK.EXE  linker: 

1 1  ink  /n  /Tw  /L\borl andc\l ib  c0ws  hellowin,  hellowin, 

NUL,  import  mathws  cws,  hellowin 

The  fields  of  TLINK  are  defined  in  the  same  manner  as  LINK,  but  the  library  names 
are  defined  differently  and  more  switches  are  required.  The  /n  switch  inhibits  the  default 
library  search,  the  /Tw  switch  creates  a  Windows  executable  file,  and  the  /L  switch  speci¬ 
fies  a  directory  for  the  libraries.  The  object  module  is  linked  with  the  COWS.OBJ  startup 
code  for  Windows  programs. 

The  second  indented  command  in  the  first  section  of  the  make  file  runs  the  Windows 
resource  compiler,  RC.EXE: 

rc  -t  hellowin.exe 
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The  resource  compiler  sets  a  couple  of  flags  in  the  HELLOWIN.EXE  file  to  indicate 
that  this  is  a  Windows  3-compatible  application.  Primarily,  this  avoids  a  Windows  3  mes¬ 
sage  that  warns  the  user  that  the  program  may  crash  because  it  has  not  been  modified  for 
protected-mode  operation.  The  -t  flag  indicates  a  protect-mode  only  application.  Later  on, 
we’ll  use  the  resource  compiler  to  add  menus  and  dialog  boxes  to  our  Windows  programs. 

The  C  Source  Code  File 

The  second  file  in  Figure  1-5  is  HELLOWIN.C,  the  C  source  code  file.  It  may  take  a  while 
before  you  recognize  that  this  program  is  indeed  written  in  C! 

Let’s  first  take  a  global  look  at  HELLOWIN.C  before  getting  into  details.  The  file  con¬ 
tains  only  two  functions:  WinMain  and  WndProc.  WinMain  is  the  entry  point  to  the  pro¬ 
gram.  It  is  the  equivalent  of  the  standard  C  main  function.  Every  Windows  program  has  a 
WinMain  function. 

WndProc  is  the  window  procedure  for  HELLOWIN’s  window.  This  function  pro¬ 
cesses  messages  to  the  window.  No  code  in  HELLOWIN.C  calls  WndProc  directly: 
WndProc  is  called  only  from  Windows.  However,  there  is  a  reference  to  WndProc  in  Win¬ 
Main ,  which  is  why  the  function  is  declared  near  the  top  of  the  program  before  WinMain. 

The  Windows  Function  Calls 

HELLOWIN  makes  calls  to  no  less  than  16  Windows  functions.  In  the  order  they  occur  in 
HELLOWIN,  these  functions  (with  a  brief  description)  are: 

■  Loadlcon — loads  an  icon  for  use  by  a  program. 

■  LoadCursor — loads  a  mouse  cursor  for  use  by  a  program. 

■  GetStockObject — obtains  a  graphics  object  (in  this  case  a  brush  used  for 
painting  the  window’s  background). 

■  RegisterClass — registers  a  window  class  for  the  program’s  window. 

■  CreateWindow — creates  a  window  based  on  a  window  class. 

■  ShowWindow — displays  the  window  on  the  screen. 

■  UpdateWindow — directs  the  window  to  paint  itself. 

■  GetMessage — obtains  a  message  from  the  message  queue. 

■  TranslateMessage — translates  some  keyboard  messages. 

■  DispatchMessage — sends  a  message  to  a  window  procedure. 

■  BeginPaint — initiates  the  beginning  of  window  painting. 

■  GetClientRect — obtains  the  dimensions  of  the  window’s  client  area. 
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■  DrawText — displays  a  text  string. 

■  EndPaint — ends  window  painting. 

■  PostQuitMessage — inserts  a  “quit”  message  into  the  message  queue. 

■  DefWindowProc — performs  default  processing  of  messages. 

These  functions  are  documented  in  the  Windows  Programmer’s  Reference  and 
declared  in  WINDOWS.H.  I’ll  discuss  each  of  the  functions  as  we  encounter  them  while 
dissecting  the  program. 

Uppercase  Identifiers 

You’ll  notice  the  use  of  quite  a  few  uppercase  identifiers  in  HELLOWIN.C.  These  iden¬ 
tifiers  are  defined  in  WINDOWS.H. 

Several  of  these  identifiers  contain  a  two -letter  or  three-letter  prefix  followed  by  an 
underscore: 

CS-HREDRAW  DT-SINGLELINE  WM-DESTROY 

IDI -APPLICATION  CS-VREDRAW  DT-CENTER 

WS-OVERLAPPEDWINDOW  IDC-ARROW  DT-VCENTER 

WM -PAINT  CW-USEDEFAULT 

These  are  simply  numeric  constants.  The  prefix  indicates  a  general  category  to  which  the 
constant  belongs,  as  indicated  in  this  table: 


Prefix 

Category 

cs 

Class  style 

IDI 

ID  for  an  icon 

IDC 

ID  for  a  cursor 

ws 

Window  style 

cw 

Create  window 

WM 

Window  message 

DT 

Draw  text 

You  almost  never  need  to  remember  numeric  constants  when  programming  for 
Windows.  Virtually  every  numeric  constant  used  in  Windows  has  an  identifier  defined  in 
WINDOWS.H. 

New  Data  Types 

Other  identifiers  used  in  HELLOWIN.C  are  new  data  types,  also  defined  in  WINDOWS.H. 
The  ones  used  in  the  program  are: 
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Data  Type 

Meaning 

FAR 

Same  as  far 

PASCAL 

Same  as  pascal 

UINT 

Unsigned  integer  (16  bits) 

LONG 

Signed  long  integer  (32  bits) 

LPSTR 

Far  (or  long)  pointer  to  a  character  string 

These  are  fairly  self-explanatory.  The  people  who  originally  developed  Windows  were 
prescient  enough  to  realize  that  it  would  someday  be  ported  to  other  microprocessors. 
These  new  data  types  were  defined  to  ease  the  porting  of  Windows  applications  to  other 
architectures.  Rather  than  use  machine-specific  data  sizes  (such  as  the  size  of  C  integer), 
the  new  data  types  were  devised  to  keep  programs  consistent  regardless  of  the  processor 
on  which  they  run. 

You  should  use  these  defined  data  types  rather  than  C  data  types  to  ease  the  porting 
of  your  programs  to  the  32-bit  Windows  architecture  expected  in  the  future. 

HELLOWIN  also  uses  four  data  structures  (which  I’ll  discuss  later  in  this  chapter) 
defined  in  WINDOWS.H: 


Structure 

Meaning 

MSG 

Message  structure 

WNDCLASS 

Window  class  structure 

PAINTSTRUCT 

Paint  structure 

RECT 

Rectangle  structure 

The  first  two  data  structures  are  used  in  WinMain  to  define  two  structures  named  rasgand 
wndclass.  The  second  two  are  used  in  WndProc to  define  two  structures  named psand  red . 

Getting  a  Handle  on  Handles 

Finally,  there  are  three  uppercase  identifiers  for  various  types  of  “handles”: 

Identifier 

Meaning 

HANDLE 

Generic  handle 

HWND 

Handle  to  a  window 

HDC 

Handle  to  a  device  context 

Handles  are  used  quite  frequently  in  Windows.  Before  the  chapter  is  over,  you  also 
encounter  HICON  (a  handle  to  an  icon),  HCURSOR  (a  handle  to  a  mouse  cursor),  and 
HBRUSH  (a  handle  to  a  graphics  brush). 
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A  handle  is  simply  a  16-bit  number  that  refers  to  an  object.  The  handles  in  Windows 
are  similar  to  file  handles  used  in  conventional  C  or  MS-DOS  programming.  A  program 
almost  always  obtains  a  handle  by  calling  a  Windows  function.  The  program  uses  the 
handle  in  other  Windows  functions  to  refer  to  the  object.  The  actual  value  of  the  handle  is 
unimportant  to  your  program,  but  the  Windows  module  that  gives  your  program  the 
handle  knows  how  to  use  it  to  reference  the  object. 

Hungarian  Notation 

You  may  also  notice  that  some  of  the  variables  in  HELLOWIN.C  have  peculiar-looking 
names.  One  example  is  IpszCmdParam,  passed  as  a  parameter  to  WinMain. 

Many  Windows  programmers  use  a  variable-naming  convention  known  as  Hun¬ 
garian  notation,  in  honor  of  the  legendary  Microsoft  programmer  Charles  Simonyi.  Very 
simply,  the  variable  name  begins  with  a  lowercase  letter  or  letters  that  denote  the  data  type 
of  the  variable.  For  example,  the  Ipsz  prefix  in  IpszCmdParam  stands  for  “long  pointer  to  a 
string  terminated  by  zero.” 

The  h  prefix  in  hlnstance  and  hPrevInstance  stands  for  “handle”;  the  n  prefix  in 
nCmdShow  stands  for  “number,”  and  usually  specifies  an  integer.  Two  of  the  parameters 
to  WndProc  also  use  Hungarian  notation:  wParam  is  a  UINT  (the  “w”  stands  for  “word”), 
and  iParam  is  a  LONG. 

When  naming  structure  variables,  you  can  use  the  structure  name  (or  an  abbrevia¬ 
tion  of  the  structure  name)  in  lowercase  either  as  a  prefix  to  the  variable  name  or  as  the 
entire  variable  name.  For  example,  in  the  WinMain  function  in  HELLOWIN.C,  the  msg 
variable  is  a  structure  of  the  MSG  type;  wndclass  is  a  structure  of  the  WNDCLASS  type.  In 
the  WndProc  function,  ps  is  a  PAINTSTRUCT  structure  and  rect  is  a  RECT  structure. 

Hungarian  notation  helps  you  avoid  errors  in  your  code  before  they  turn  into  bugs. 
Because  the  name  of  a  variable  describes  both  the  use  of  a  variable  and  its  data  type,  you 
are  much  less  inclined  to  make  coding  errors  involving  mismatched  data  types. 

The  variable  name  prefixes  I’ll  be  using  in  this  book  are  shown  in  the  following  table: 


Prefix 

Data  Type 

C 

char 

by 

BYTE  (unsigned  char) 

n 

short  or  int 

i 

int 

x,y 

short  (used  as  ^-coordinate  or  ^-coordinate) 

cx,  cy 

short  (used  as  x  or  y  length;  the  c  stands  for  “count”) 

b 

BOOL  (int) 

w 

UINT  (unsigned  int)  or  WORD  (unsigned  word) 

(continued) 
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continued 


Prefix 

Data  Type 

1 

LONG  (long) 

dw 

DWORD  (unsigned  long) 

fn 

function 

s 

string 

sz 

string  terminated  by  0  byte 

The  Program  Entry  Point 

With  this  global  look  at  HELLOWIN.C  out  of  the  way,  we  can  now  begin  the  line-by-line 
dissection  of  the  program.  The  code  begins  with  an  # include  statement  to  include  the 
WINDOWS.H  header  file: 

#include  <windows.h> 

WINDOWS.H  contains  declarations  of  the  Windows  functions,  the  Windows  structures, 
the  new  data  types,  and  numeric  constants. 

This  is  followed  by  a  forward  declaration  of  the  WndProc  function: 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

The  forward  declaration  is  required  because  WndProc  is  referenced  by  some  code  in  the 
WinMain  function. 

In  a  C  program  written  for  a  conventional  environment,  the  entry  point  is  a  function 
called  main.  This  is  where  the  program  begins  execution.  (Actually,  the  main  function  is 
the  entry  point  to  the  part  of  the  program  written  by  the  programmer.  Usually  the  C  com¬ 
piler  will  insert  some  start-up  code  in  the  executable  file.  The  start-up  code  then  calls 
main.)  The  entry  point  of  a  Windows  program  is  a  function  called  WinMain.  (As  is  the 
case  with  main ,  WinMain  is  actually  called  from  some  start-up  code  inserted  into  the  exe¬ 
cutable  file.)  WinMain  is  always  defined  like  this: 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  lpszCmdParam,  int  nCmdShow) 

This  function  uses  the  PASCAL  calling  sequence  and  returns  an  integer  to  the  start-up 
code.  The  function  must  be  named  WinMain.  It  has  four  parameters. 

The  hlnstance  parameter  is  called  the  “instance  handle.”  This  is  a  number  that 
uniquely  identifies  the  program  when  it  is  running  under  Windows.  It  could  be  that  the 
user  is  running  multiple  copies  of  the  same  program  under  Windows.  (For  example,  most 
Windows  users  at  one  time  or  another  have  loaded  multiple  versions  of  the  CLOCK  pro¬ 
gram  to  see  what  happens.)  Each  copy  is  called  an  “instance,”  and  each  has  a  different 
hlnstance  value.  The  instance  handle  is  comparable  to  a  “task  ID”  or  “process  ID”  number 
common  in  mulitasking  operating  systems. 
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The  hPrevInstance  (“previous  instance”)  parameter  is  the  instance  handle  of  the 
most  recent  previous  instance  of  the  same  program  that  is  still  active.  If  no  other  copies  of 
the  program  are  currently  loaded,  then  hPrevInstance  will  be  0  or  NULL. 

The  IpszCmdParam  parameter  is  a  long  (or  far)  pointer  to  a  O-terminated  string  that 
contains  any  command-line  parameters  passed  to  the  program.  You  can  run  a  Windows  pro¬ 
gram  with  a  command-line  parameter  by  typing  the  program  name  and  the  parameter  into 
the  Run  dialog  box  invoked  from  either  the  Program  Manager  or  the  File  Manager. 

The  nCmdShow  parameter  is  a  number  indicating  how  the  window  is  to  be  initially 
displayed  in  Windows.  This  number  is  assigned  by  whatever  program  executes  the  pro¬ 
gram  to  run  under  Windows.  Programs  do  not  often  need  to  examine  this  number,  but  they 
can  if  they  want  to.  In  most  cases  the  number  is  either  a  1  or  a  7.  But  it’s  best  not  to  think 
of  the  value  as  a  1  or  a  7.  Rather,  think  of  the  value  as  SW_SHOWNORMAL  (defined  in 
WINDOWS.H  as  1)  or  SW_SHOWMINNOACTIVE  (defined  as  7).  The  SW  prefix  in  these 
identifiers  stands  for  “show  window.”  This  indicates  whether  the  user  launched  the  pro¬ 
gram  to  be  displayed  as  a  normal  window  or  to  be  initially  minimized. 

Registering  the  Window  Class 

A  window  is  always  created  based  on  a  window  class.  The  window  class  identifies  the  win¬ 
dow  procedure  that  processes  messages  to  the  window.  This  is  important,  so  I’ll  repeat  it: 
A  window  is  always  created  based  on  a  window  class.  The  window  class  identifies  the 
window  procedure  that  processes  messages  to  the  window. 

More  than  one  window  can  be  created  based  on  a  single  window  class.  For  example, 
all  button  windows  in  Windows  are  created  based  on  the  same  window  class.  The  window 
class  defines  the  window  procedure  and  some  other  characteristics  of  the  windows  that 
are  created  based  on  that  class.  When  you  create  a  window,  you  define  additional  charac¬ 
teristics  of  the  window  that  are  unique  to  that  window. 

Before  you  create  a  window  for  your  program,  you  must  register  a  window  class  by 
calling  RegisterClass.  The  RegisterClass  function  requires  a  single  parameter:  a  pointer  to  a 
structure  of  type  WNDCLASS.  The  WNDCLASS  structure  is  defined  in  WINDOWS.H 
like  this: 

typedef  struct  tagWNDCLASS 
{ 


UINT 

style  ; 

WNDPROC 

IpfnWndProc  ; 

int 

cbClsExtra  ; 

int 

cbWndExtra  ; 

HINSTANCE 

hlnstance  ; 

HICON 

hlcon  ; 

HCURSOR 

hCursor  ; 

HBRUSH 

hbrBackground 

LPCSTR 

IpszMenuName 

LPCSTR 

} 

WNDCLASS  ; 

lpszClassName 
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In  WinMain ,  you  must  define  a  structure  of  type  WNDCLASS,  generally  like  this: 

WNDCLASS  wndclass  ; 

You  then  define  the  10  fields  of  the  structure  and  call  RegisterClass : 

RegisterClass  (&wndclass)  ; 

Only  the  first  instance  of  a  program  needs  to  register  the  window  class.  The  window 
class  then  becomes  available  to  all  subsequent  instances  of  the  program.  For  this  reason, 
HELLOWIN  initializes  the  fields  of  the  WNDCLASS  structure  and  calls  RegisterClass  only  if 
hPrevInstance  equals  NULL. 

The  WNDCLASS  structure  has  10  fields.  The  2  most  important  fields  are  the  last  and 
the  second.  The  last  field  is  the  name  of  the  window  class  (which  is  generally  the  same  as 
the  name  of  the  program).  The  second  field  ( IpfnWndProc )  is  the  address  of  the  window 
procedure  used  for  all  windows  created  based  on  this  class  (which  is  the  function 
WndProc  in  HELLOWIN.C).  All  the  other  fields  describe  characteristics  of  all  windows 
based  on  this  window  class. 

The  statement: 

wndclass. style  =  CS_H REDRAW  !  CS_VREDRAW  ; 

combines  two  “class  style”  identifiers  with  a  C  bitwise  OR  operator.  In  WINDOWS.H,  the 
various  identifiers  beginning  with  the  CS  prefix  are  defined  as  16-bit  constants  with  1  bit 
set.  For  example,  CS_VREDRAW  is  defined  as  0x0001,  and  CS_HREDRAW  is  defined  as 
0x0002.  Identifiers  defined  in  this  way  are  sometimes  called  “bit  flags.”  You  combine  the 
bit-flag  identifiers  with  the  C  OR  operator. 

These  two  class-style  identifiers  indicate  that  all  windows  created  based  on  this  class 
are  to  be  completely  repainted  whenever  the  horizontal  window  size  (CS-HREDRAW)  or 
the  vertical  window  size  (CS-VREDRAW)  changes.  If  you  resize  HELLOWIN’s  window, 
you’ll  see  that  the  text  string  is  redrawn  to  be  in  the  new  center  of  the  window.  These  two 
identifiers  ensure  that  this  happens. 

The  second  field  of  the  WNDCLASS  structure  is  initialized  by  the  statement: 

wndcl ass . 1 pfnWndProc  =  WndProc  ; 

This  sets  the  window  procedure  for  this  window  class  to  WndProc ,  which  is  the  second 
function  in  HELLOWIN.C.  This  window  procedure  will  process  all  messages  to  all  win¬ 
dows  created  based  on  this  window  class.  The  Ipfn  prefix  in  the  field  name  is  Hungarian 
notation  for  “long  pointer  to  a  function.” 

The  next  two  statements: 

wndclass. cbClsExtra  =  0  ; 

wndclass. cbWndExtra  =  0  ; 
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reserve  some  extra  space  in  the  class  structure  and  the  window  structure  that  Windows 
maintains  internally.  A  program  can  use  this  extra  space  for  its  own  purpose.  HELLOWIN 
does  not  use  this  feature,  so  0  is  specified.  The  cb  prefix  in  the  field  names  stands  for  a 
“count  of  bytes.” 

The  next  field  is  simply  the  instance  handle  of  the  program  (which  is  one  of  the 
parameters  to  WinMairi): 

wndclass.hlnstance  =  hlnstance  ; 

The  statement: 

wndclass.hlcon  =  Loadlcon  (NULL,  IDI.APPLICATION)  ; 

sets  an  icon  for  all  windows  created  based  on  this  window  class.  The  icon  is  a  small  bitmap 
picture  that  appears  when  the  program  is  minimized.  Later  in  this  book  you’ll  learn  how  to 
create  customized  icons  for  your  Windows  programs.  Right  now,  well  take  an  easy  ap¬ 
proach  and  use  a  predefined  icon. 

To  obtain  a  handle  to  a  predefined  icon,  you  call  Loadlcon  with  a  first  parameter  set 
to  NULL.  (When  loading  your  own  customized  icon,  this  parameter  would  be  set  to  the  in¬ 
stance  handle  of  the  program.)  The  second  parameter  is  an  identifier  beginning  with  the 
IDI  (“ID  for  an  icon”)  defined  in  WINDOWS.H.  The  IDI -APPLICATION  icon  is  simply  a 
white  square  with  a  black  outline.  The  Loadlcon  function  returns  a  handle  to  this  icon.  We 
don’t  really  care  about  the  value  of  this  handle.  It’s  simply  used  to  set  the  value  of  the  hLcon 
field.  The  hLcon  field  is  defined  in  the  WNDCLASS  structure  to  be  of  type  HICON,  which 
stands  for  “handle  to  an  icon.” 

The  statement: 

wndclass.hCursor  =  LoadCursor  (NULL,  I DC_ARR0W )  ; 

is  very  similar  to  the  previous  statement.  The  LoadCursor  function  loads  a  predefined 
mouse  cursor  known  as  IDC -ARROW  and  returns  a  handle  to  the  cursor.  This  handle  is 
assigned  to  the  hCursoriicXd  of  the  WNDCLASS  structure.  When  the  mouse  cursor  appears 
over  the  client  area  of  a  window  that  is  created  based  on  this  class,  the  cursor  becomes  a 
small  arrow. 

The  next  field  specifies  the  background  color  of  the  client  area  of  windows  created 
based  on  this  class.  The  &£>rprefix  of  the  hbrBackground  field  name  stands  for  “handle  to 
a  brush.”  A  brush  is  a  graphics  term  that  refers  to  a  colored  pattern  of  pixels  used  to  fill  an 
area.  Windows  has  several  standard,  or  “stock,”  brushes.  The  GetStockObject  call  shown 
here  returns  a  handle  to  a  white  brush: 

wndclass. hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 

This  means  the  background  of  the  client  area  of  the  window  will  be  solid  white,  which  is  a 
common  choice. 
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The  next  field  specifies  the  window  class  menu.  HELLOWIN  has  no  application 
menu,  so  the  field  is  set  to  NULL: 

wndclass.lpszMenuName  =  NULL  ; 

Finally  the  class  must  be  given  a  name.  This  is  the  same  as  the  name  of  the  program, 
which  is  the  “HelloWin”  string  stored  in  the  szAppName  variable: 

wndclass.lpszClassName  =  szAppName  ; 

When  all  10  fields  of  the  structure  have  been  initialized,  HELLOWIN  registers  the 
window  class  by  calling  RegisterClass.  The  only  parameter  to  the  function  is  a  pointer  to 
the  WNDCLASS  structure: 

RegisterClass  (&wndclass)  ; 


Creating  the  Window 

The  window  class  defines  general  characteristics  of  a  window,  thus  allowing  the  same  win¬ 
dow  class  to  be  used  for  creating  many  different  windows.  When  you  actually  create  a 
window  by  calling  CreateWindow ,  you  specify  more  detailed  information  about  the  win¬ 
dow.  Rather  than  using  a  data  structure  as  RegisterClass  does,  the  CreateWindow  call 
requires  all  the  information  to  be  passed  as  parameters  to  the  function.  Here’s  the 
CreateWindow  call  in  HELLOWIN.C: 


hwnd  =  CreateWindow  (szAppName, 

"The  Hello  Program", 
WS_OVERLAPP EDWIN DOW , 
CW_USEDEFAULT, 
CW_USEDEFAULT, 

CW_US  EDE  FAU  LT , 
CW_USEDEFAULT, 

NULL, 

NULL, 

hlnstance, 

NULL)  ; 


//  window  class  name 
//  window  caption 
//  window  style 
//  initial  x  position 
//  initial  y  position 
//  initial  x  size 
//  initial  y  size 
//  parent  window  handle 
//  window  menu  handle 
//  program  instance  handle 
//  creation  parameters 


The  Microsoft  and  Borland  C  compilers  recognize  the  //  symbol  for  single-line  comments. 
The  comments  describe  the  parameters  to  the  CreateWindow  function. 

Although  you  need  to  register  a  window  class  only  for  the  first  instance  of  a  program, 
you  must  create  a  window  separately  for  each  instance.  Each  instance  has  its  own  window, 
and  all  the  windows  are  based  on  the  same  window  class. 

The  parameter  marked  “window  class  name”  is  szAppName ,  which  contains  the 
string  “HelloWin” — the  name  of  the  window  class  we  just  registered.  This  is  how  the  win¬ 
dow  is  associated  with  the  window  class. 

The  window  created  by  this  program  is  a  normal  overlapped  window  with  a  caption 
bar,  a  system  menu  box  to  the  left  of  the  caption  bar,  minimize  and  maximize  icons  to 
the  right  of  the  caption  bar,  and  a  thick  window-sizing  border.  That’s  a  standard  style  of 
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windows,  and  it  has  the  WINDOWS.H  name  WS-OVERLAPPEDWINDOW,  which  appears 
as  the  “window  style”  parameter.  The  “window  caption”  is  the  text  that  will  appear  in  the 
caption  bar. 

The  parameters  marked  “initial  x  position”  and  “initial  y  position”  specify  the  initial 
position  of  the  upper  left  corner  of  the  window  relative  to  the  upper  left  corner  of  the 
screen.  By  using  the  identifier  CW_USE DEFAULT  for  these  parameters,  we’re  indicating  we 
want  Windows  to  use  the  default  position  for  an  overlapped  window.  (CW_USEDEFAULT 
is  defined  as  0x8000.)  By  default,  Windows  positions  successive  overlapped  windows  at 
stepped  horizontal  and  vertical  offsets  from  the  upper  left  corner  of  the  display. 

Similarly,  the  “initial  x  size”  and  “initial  y  size”  parameters  specify  the  width  and 
height  of  the  window.  The  CW_USEDEFAULT  identifier  again  indicates  that  we  want  Win¬ 
dows  to  use  a  default  size  for  the  window.  The  default  size  extends  to  the  right  side  of  the 
display  and  above  the  icon  area  at  the  bottom  of  the  screen. 

The  parameter  marked  “parent  window  handle”  is  set  to  NULL  because  this  window 
has  no  parent  window.  (When  a  parent-child  relationship  exists  between  two  windows, 
the  child  window  always  appears  on  the  surface  of  its  parent.)  The  “window  menu  handle” 
is  also  set  to  NULL  because  the  window  has  no  menu.  The  “program  instance  handle”  is  set 
to  the  instance  handle  passed  to  the  program  as  a  parameter  of  WinMain.  Finally,  a 
“creation  parameters”  pointer  is  set  to  NULL.  You  could  use  this  pointer  to  access  some 
data  that  you  might  later  want  to  reference  in  the  program. 

The  CreateWindow call  returns  a  handle  to  the  created  window.  This  handle  is  saved 
in  the  variable  humd,  which  is  defined  to  be  of  type  HWND  (handle  to  a  window).  Every 
window  in  Windows  has  a  handle.  Your  program  uses  the  handle  to  refer  to  the  window. 
Many  Windows  functions  require  hwnd  as  a  parameter  so  that  Windows  knows  to  which 
window  the  function  applies.  If  a  program  creates  many  windows,  each  has  a  different 
handle.  The  handle  to  a  window  is  one  of  the  most  important  handles  a  Windows  program 
(pardon  the  expression)  handles. 

Displaying  the  Window 

After  the  CreateWindow  call  returns,  the  window  has  been  created  internally  in  Windows. 
However,  the  window  does  not  yet  appear  on  the  video  display.  Two  more  calls  are 
needed.  The  first  is: 

ShowWindow  (hwnd,  nCmdShow)  ; 

The  first  parameter  is  the  handle  to  the  window  just  created  by  CreateWindow.  The  second 
parameter  is  the  nCmdShow  value  passed  as  a  parameter  to  WinMain .  This  determines 
how  the  window  is  to  be  initially  displayed  on  the  screen.  If  nCmdShow  is  SW_SHOW- 
NORMAL  (equal  to  1),  the  window  is  displayed  normally.  If  nCmdShow  is  SW_SHOWMIN- 
NOACTIVE  (equal  to  7),  then  the  window  is  initially  displayed  as  an  icon. 
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The  ShowWindow  function  puts  the  window  (or  icon)  on  the  display.  If  the  second 
parameter  to  ShowWindow  is  SW_SHOWNORMAL,  the  client  area  of  the  window  is  erased 
with  the  background  brush  specified  in  the  window  class.  The  function  call: 

UpdateWindow  (hwnd)  ; 

then  causes  the  client  area  to  be  painted.  It  accomplishes  this  by  sending  the  window  pro¬ 
cedure  (the  WndProc  function  in  HELLOWIN.C)  a  WM_PAINT  message.  We’ll  examine 
shortly  how  WndProc  deals  with  this  message. 

The  Message  Loop 

After  the  UpdateWindow  call,  the  window  is  fully  visible  on  the  video  display.  The  pro¬ 
gram  must  now  make  itself  ready  to  read  keyboard  and  mouse  input  from  the  user.  Win¬ 
dows  maintains  a  “message  queue”  for  each  Windows  program  currently  running  under 
Windows.  When  an  input  event  occurs,  Windows  translates  the  event  into  a  “message”  that 
it  places  in  the  program’s  message  queue. 

A  program  retrieves  these  messages  from  the  message  queue  by  executing  a  block  of 
code  known  as  the  “message  loop”: 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

The  msg  variable  is  a  structure  of  type  MSG,  which  is  defined  in  WINDOWS.H  as  follows: 

typedef  struct  tagMSG 
{ 


HWND 

hwnd  ; 

UINT 

message 

WPARAM 

wParam 

LPARAM 

1 Param 

DWORD 

time  ; 

POINT 

} 

MSG  ; 

pt  ; 

The  POINT  data  type  is  yet  another  structure,  defined  like  this: 

typedef  struct  tagPOINT 
{ 

int  x  ; 
int  y  ; 

} 

POINT  ; 
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The  GetMessagecM  that  begins  the  message  loop  retrieves  a  message  from  the  mes¬ 
sage  queue: 

GetMessage  (&msg,  NULL,  0,  0)  ; 

This  call  passes  to  Windows  a  far  pointer  to  the  MSG  structure  called  msg.  The  second, 
third,  and  fourth  parameters  are  set  to  NULL  or  0  to  indicate  that  the  program  wants  all 
messages  for  all  windows  created  by  the  program.  Windows  fills  in  the  fields  of  the 
message  structure  with  the  next  message  from  the  message  queue.  The  fields  of  this 
structure  are: 

■  hwnd — the  handle  to  the  window  to  which  the  message  is  directed.  In 
the  HELLOWIN  program,  this  is  the  same  as  the  hwnd  value  returned 
from  CreateWindow ,  because  that’s  the  only  window  this  program  has. 

■  message — the  message  identifier.  This  is  a  number  that  identifies  the 
message.  For  each  message,  there  is  a  corresponding  identifier  defined  in 
WINDOWS.H  that  begins  with  the  prefix  WM  (“window  message”).  For 
example,  if  you  position  the  mouse  pointer  over  HELLOWIN’s  client  area 
and  press  the  left  mouse  button,  Windows  will  put  a  message  in  the 
message  queue  with  a  message  field  equal  to  WM_LBUTTONDOWN, 
which  is  the  value  0x0201. 

■  wParam — a  l6-bit  “message  parameter,”  the  meaning  and  value  of  which 
depend  on  the  particular  message. 

■  IParam — a  32-bit  message  parameter  dependent  on  the  message. 

■  time — the  time  the  message  was  placed  in  the  message  queue. 

■  pt — the  mouse  coordinates  at  the  time  the  message  was  placed  in  the 
message  queue. 

If  the  message  field  of  the  message  retrieved  from  the  message  queue  is  anything 
except  WM-QUIT  (which  equals  0x0012),  then  GetMessage  returns  a  nonzero  value.  A 
WM-QUIT  message  causes  the  program  to  fall  out  of  the  message  loop.  The  program  then 
terminates,  returning  the  wParam  member  of  the  msg  structure. 

The  statement: 

TranslateMessage  (&msg)  ; 

passes  the  msg  structure  back  to  Windows  for  some  keyboard  translation.  (I’ll  discuss  this 
more  in  Chapter  3.)  The  statement: 

DispatchMessage  (&msg)  ; 

again  passes  the  msg  structure  back  to  Windows.  Windows  then  sends  the  message  to  the 
appropriate  window  procedure  for  processing.  That  window  procedure  is  the  WndProc 
function  in  HELLOWIN.  After  WndProc  processes  the  message,  it  then  returns  to 
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Windows,  which  is  still  servicing  the  DispatchMessage  call.  When  Windows  returns  to 
HELLOWIN  following  the  DispatchMessage  call,  the  message  loop  continues  with  the  next 
GetMessage  call. 

The  Window  Procedure 

All  that  I’ve  described  so  far  is  really  just  overhead.  The  window  class  has  been  registered, 
the  window  has  been  created,  the  window  has  been  displayed  on  the  screen,  and  the  pro¬ 
gram  has  entered  a  message  loop  to  retrieve  messages  from  the  message  queue. 

The  real  action  occurs  in  the  window  procedure,  which  Windows  programmers 
commonly  call  a  “window  proc”  (pronounced  “prock”).  The  window  procedure  deter¬ 
mines  what  the  window  displays  in  its  client  area  and  how  the  window  responds  to 
user  input. 

In  HELLOWIN,  the  window  procedure  is  the  function  called  WndProc.  A  window 
procedure  can  have  any  name.  A  Windows  program  can  contain  more  than  one  window 
procedure.  A  window  procedure  is  always  associated  with  a  particular  window  class  that 
you  register  by  calling  RegisterClass.  The  CreateWindoiv  function  creates  a  window  based 
on  a  particular  window  class.  More  than  one  window  can  be  created  based  on  the  same 
window  class. 

A  window  procedure  is  always  defined  like  this: 

long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

Note  that  the  four  parameters  to  the  window  procedure  are  identical  to  the  first  four  fields 
of  the  MSG  structure. 

The  first  parameter  is  hwnd ,  the  handle  to  the  window  receiving  the  message.  This 
is  the  same  handle  returned  from  the  CreateWindow  function.  For  a  program  like 
HELLOWIN,  which  creates  only  one  window,  this  is  the  only  window  handle  the  program 
knows  about.  If  a  program  creates  multiple  windows  based  on  the  same  window  class  (and 
hence  the  same  window  procedure),  then  hwnd  identifies  the  particular  window  receiving 
the  message. 

The  second  parameter  is  a  number  (specifically,  a  16-bit  unsigned  integer  or  UINT) 
that  identifies  the  message.  The  last  two  parameters  (a  UINT  called  wParam  and  a  32-bit 
signed  long  integer  or  LONG  called  iParani)  provide  more  information  about  the  message. 
These  are  called  “message  parameters.”  What  these  parameters  contain  is  specific  to  each 
type  of  message. 

Processing  the  Messages 

Each  message  that  a  window  procedure  receives  is  identified  by  a  number,  which  is  the 
message  parameter  to  the  window  procedure.  The  WINDOWS.H  header  file  defines  iden¬ 
tifiers  beginning  with  the  prefix  WM  (“window  message”)  for  each  message  parameter. 
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Generally,  Windows  programmers  use  a  switch  and  case  construction  to  determine 
what  message  the  window  procedure  is  receiving  and  how  to  process  it  accordingly.  When 
a  window  procedure  processes  a  message,  it  should  return  0  from  the  window  procedure. 
All  messages  that  a  window  procedure  chooses  not  to  process  must  be  passed  to  a  Win¬ 
dows  function  named  DefWindowProc.  The  value  returned  from  DefWindowProc  must 
be  returned  from  the  window  procedure. 

In  HELLOWIN,  WndProc  chooses  to  process  only  two  messages:  WM_PAINT  and 
WM-DESTROY.  The  window  procedure  is  structured  like  this: 

switch  (message) 

{ 

case  WM_PAI NT  : 

[ process  WM-PAINT message] 
return  0  ; 

case  WM_DESTROY  : 

[ process  WM-DESTROY  message] 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

It  is  essential  to  call  DefWindowProc  for  default  processing  of  all  messages  that  your 
window  procedure  does  not  process. 

The  WM.PAINT  Message 

The  first  message  that  WndProc  processes  is  WM_PAINT.  This  message  is  extremely  im¬ 
portant  in  Windows  programming.  It  informs  a  program  when  part  or  all  of  the  window’s 
client  area  is  “invalid”  and  must  be  repainted. 

How  does  a  client  area  become  invalid?  When  the  window  is  first  created,  the  entire 
client  area  is  invalid  because  the  program  has  not  yet  drawn  anything  on  the  window.  The 
first  WM-PAINT  message  (which  normally  occurs  when  the  program  calls  UpdateWindow 
in  WinMain)  directs  the  window  procedure  to  draw  something  on  the  client  area. 

When  you  resize  HELLOWIN’s  window,  the  client  area  also  becomes  invalid.  You’ll 
recall  that  the  style  parameter  of  HELLOWIN’s  wndclass  structure  was  set  to  the  flags 
CS-HREDRAW  and  CS-VREDRAW.  This  directs  Windows  to  invalidate  the  whole  window 
when  the  size  changes.  The  window  procedure  receives  a  WM_PAINT  message. 

When  you  minimize  HELLOWIN  to  be  displayed  as  an  icon  and  then  restore  the  win¬ 
dow  again  to  its  previous  size,  Windows  does  not  save  the  contents  of  the  client  area. 
Under  a  graphical  environment,  this  would  be  too  much  data.  Instead,  Windows  invali¬ 
dates  the  window.  The  window  procedure  receives  a  WM-PAINT  message  and  itself 
restores  the  contents  of  its  window. 
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When  you  move  windows  around  so  they  overlap,  Windows  does  not  save  the  area  of 
a  window  covered  by  another  window.  When  that  area  of  the  window  is  later  uncovered,  it 
is  flagged  as  invalid.  The  window  procedure  receives  a  WM -PAINT  message  to  repaint  the 
contents  of  the  window. 

WM-PAINT  processing  almost  always  begins  with  a  call  to  BeginPaint : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 
and  ends  with  a  call  to  EndPaint : 

EndPaint  (hwnd,  &ps)  ; 

In  both  cases,  the  first  parameter  is  a  handle  to  the  program’s  window  and  the  second 
parameter  is  a  pointer  to  a  structure  of  type  PAINTSTRUCT.  The  PAINTSTRUCT  structure 
contains  some  information  that  a  window  procedure  can  use  for  painting  the  client  area. 
(I’ll  discuss  the  fields  of  this  structure  in  the  next  chapter.) 

During  the  BeginPaint  c all,  Windows  erases  the  background  of  the  client  area  if  it 
hasn’t  been  erased  already.  It  erases  the  background  using  the  brush  specified  in  the 
hbrBackground  field  of  the  WNDCLASS  structure  used  to  register  the  window  class.  In  the 
case  of  HELLOWIN,  this  is  a  stock  white  brush,  which  means  that  Windows  erases  the 
background  of  the  window  by  coloring  it  white.  The  BeginPaint  call  validates  the  entire 
client  area  and  returns  a  “handle  to  a  device  context.”  A  device  context  refers  to  a  physical 
output  device  (such  as  a  video  display)  and  its  device  driver.  You  need  the  device  context 
handle  to  display  text  and  graphics  in  the  client  area  of  a  window.  Using  the  device  context 
handle  returned  from  BeginPaint ,  you  cannot  draw  outside  the  client  area,  even  if  you  try. 
EndPaint  releases  the  device  context  handle  so  that  it  is  no  longer  valid. 

If  a  window  procedure  does  not  process  WM-PAINT  messages  (which  is  very  rare), 
they  must  be  passed  on  to  DefWindowProc.  DefWindowProc  simply  calls  BeginPaint  and 
EndPaint  in  succession  so  that  the  client  area  is  validated. 

After  WndProc  calls  BeginPaint ,  it  calls  GetClientRect : 

GetClientRect  (hwnd,  &rect)  ; 

The  first  parameter  is  the  handle  to  the  program’s  window.  The  second  parameter  is  a 
pointer  to  a  variable  named  rect ,  defined  as  type  RECT  in  WndProc. 

RECT  is  a  “rectangle”  structure  defined  in  WINDOWS.H.  It  has  four  int fields  named 
left ,  top ,  right ,  and  bottom.  GetClientRect  sets  these  four  fields  to  the  dimensions  of  the  cli¬ 
ent  area  of  the  window.  The  left  and  top  fields  are  always  set  to  0.  The  right  and  bottom 
fields  are  set  to  the  width  and  height  of  the  client  area  in  pixels. 

WndProc  doesn’t  do  anything  with  this  RECT  structure  except  pass  a  pointer  to  it  as 
the  fourth  parameter  of  DrawText : 

DrawText  (hdc,  "Hello,  Windows!",  -1,  &rect, 

DT_S INGLELINE  !  DT_C ENTER  !  DT.VCENTER)  ; 
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DrawText  (as  the  name  implies)  draws  text.  Because  this  function  draws  something,  the 
first  parameter  is  a  handle  to  the  device  context  returned  from  BeginPaint.  The  second 
parameter  is  the  text  to  draw,  and  the  third  parameter  is  set  to  -1  to  indicate  that  the  text 
string  is  terminated  with  a  0  byte. 

The  last  parameter  is  a  series  of  bit  flags  defined  in  WINDOWS.H.  The  flags  indicate 
that  the  text  should  be  displayed  as  a  single  line  centered  horizontally  and  vertically  within 
the  rectangle  specified  by  the  fourth  parameter.  This  function  call  thus  causes  the  string 
“Hello,  Windows!”  to  be  displayed  centered  in  the  client  area. 

Whenever  the  client  area  becomes  invalid  (as  it  does  when  you  change  the  size  of 
the  window),  WndProc  receives  a  new  WM.PAINT  message.  WndProc  obtains  the  up¬ 
dated  window  size  by  calling  GetClientRect  and  again  displays  the  text  in  the  new  center 
of  the  window. 

The  WM  .DESTROY  Message 

The  WM.DESTROY  message  is  another  important  message.  This  message  indicates  that 
Windows  is  in  the  process  of  destroying  a  window  based  on  a  command  from  the  user.  The 
message  is  a  result  of  the  user  selecting  Close  from  the  program’s  system  menu  or  pressing 
Alt-F4. 

HELLOWIN  responds  to  this  message  in  a  standard  way  by  calling: 

PostQuitMessage  (0)  ; 

This  function  inserts  a  WM.QUIT  message  in  the  program’s  message  queue.  I  mentioned 
earlier  that  GetMessage  returns  nonzero  for  any  message  other  than  WM.QUIT  that  it 
retrieves  from  the  message  queue.  When  GetMessage  retrieves  a  WM.QUIT  message,  Get- 
Message  returns  0.  This  causes  WinMain  to  drop  out  of  the  message  loop  and  exit,  ter¬ 
minating  the  program. 

The  Module  Definition  File 

In  addition  to  the  C  source  code,  another  file  is  required  for  Windows  programs.  It  is  called 
a  “module  definition  file”  and  has  the  extension  .DEF.  The  module  definition  file  aids  the 
linker  in  creating  the  .EXE  file  by  telling  it  the  characteristics  of  the  program’s  code  and 
data  segments,  the  size  of  the  program’s  local  data  heap  (from  which  the  program  can  allo¬ 
cate  memory),  and  the  size  of  the  program’s  stack.  This  information  becomes  part  of  the 
header  section  of  the  New  Executable  file  format.  The  HELLOWIN.DEF  file  is  shown  on 
page  18. 

The  NAME  line  defines  HELLOWIN  as  a  program  (rather  than  a  dynamic  link  li¬ 
brary)  and  gives  it  a  module  name,  which  is  usually  the  name  of  the  program’s  .EXE  file. 
The  DESCRIPTION  line  simply  inserts  some  text  into  the  .EXE  file.  This  is  an  excellent 
place  for  a  copyright  notice  or  version  information.  The  EXETYPE  line  identifies  the 
program  as  a  Windows  program. 
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The  STUB  is  a  program  that  is  inserted  into  the  .EXE  file  to  be  executed  when 
someone  attempts  to  run  HELLOWIN.EXE  from  the  MS-DOS  command  line.  The 
WINSTUB.EXE  program  included  with  the  Windows  Software  Development  Kit  and  Bor¬ 
land  C++  Compiler  simply  displays  the  message  “This  program  requires  Microsoft  Win¬ 
dows”  and  terminates. 

The  CODE  statement  indicates  that  the  program’s  code  segment  is  flagged  as 
PRELOAD  (which  means  that  Windows  will  load  the  segment  into  memory  immediately) 
and  MOVEABLE  (which  means  that  Windows  can  move  the  code  segment  to  another  loca¬ 
tion  in  memory  if  it  needs  to  consolidate  blocks  of  free  memory).  The  DISCARDABLE  op¬ 
tion  makes  the  code  “discardable”  (which  means  that  Windows  can  discard  the  code 
segment  from  memory  and  later  reload  it  from  the  .EXE  file).  These  are  the  normal  options 
for  Windows  programs.  If  you  follow  proper  Windows  programming  practice,  you  will  not 
(in  theory)  encounter  any  problems  when  Windows  moves  your  code. 

The  DATA  statement  indicates  that  we  want  the  data  segment  to  be  PRELOAD, 
MOVEABLE,  and  MULTIPLE.  Again,  we  are  giving  Windows  permission  to  move  the  data 
segment  in  memory  if  necessary.  The  MULTIPLE  keyword  requests  that  each  instance  of 
the  program  gets  its  own  separate  data  segment.  This  is  necessary  because  the  data  seg¬ 
ment  contains  the  program’s  stack  and  other  data  items  that  must  be  separate  for  each  in¬ 
stance.  The  code  segment,  on  the  other  hand,  is  shared  by  all  instances  of  the  program. 

The  HEAPSIZE  line  specifies  the  amount  of  extra  local  memory  (memory  in  the  pro¬ 
gram’s  own  data  segment)  that  will  be  available  for  allocation.  The  value  depends  on  what 
the  program  needs.  HELLOWIN  doesn’t  need  to  allocate  any  local  memory,  but  we’ll  throw 
in  a  small  value  nonetheless.  Windows  can  expand  a  program’s  local  heap  if  necessary. 

Finally,  the  STACKSIZE  line  specifies  the  size  of  the  stack.  The  value  8192  bytes  is  a 
minimum  recommended  value.  You’ll  want  a  bigger  stack  size  if  your  program  has  recur¬ 
sive  functions  or  large  non -static  variables. 

THE  WINDOWS  PROGRAMMING  HURDLES 

Even  with  my  explanation  of  HELLOWIN,  the  structure  and  workings  of  the  program  are 
probably  still  somewhat  mysterious.  In  a  short  C  program  written  for  a  conventional  envi¬ 
ronment,  the  entire  program  may  be  contained  in  the  main  function.  In  HELLOWIN,  Win- 
Main  contains  only  program  overhead  necessary  to  register  the  window  class,  create  the 
window,  and  retrieve  and  dispatch  messages  from  the  message  queue. 

All  the  real  action  of  the  program  occurs  in  the  window  procedure.  In  HELLOWIN, 
this  action  is  not  much — it  simply  displays  a  text  string  in  its  window.  But  in  later  chapters 
you’ll  find  that  almost  everything  a  Windows  program  does  it  does  in  response  to  a  mes¬ 
sage  to  a  window  procedure.  This  is  one  of  the  major  conceptual  hurdles  that  you  must 
leap  to  begin  writing  Windows  programs. 
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Don’t  Call  Me,  I’ll  Call  You 

As  I  mentioned  earlier,  programmers  are  familiar  with  the  idea  of  calling  on  the  operating 
system  to  do  something.  For  instance,  C  programmers  use  the  open  or  fopen  function  to 
open  a  file.  The  library  functions  provided  with  the  compiler  have  code  that  eventually 
calls  the  operating  system  to  open  the  file.  No  problem. 

But  Windows  is  different.  Although  Windows  has  more  than  1000  functions  that  your 
program  can  call,  Windows  also  makes  calls  to  your  program,  specifically  to  the  window 
procedure  we  have  called  WndProc.  The  window  procedure  is  associated  with  a  window 
class  that  the  program  registers  by  calling  RegisterClass.  A  window  that  is  created  based  on 
this  class  uses  this  window  procedure  for  processing  all  messages  to  the  window.  Windows 
sends  a  message  to  the  window  by  calling  the  window  procedure. 

Windows  calls  WndProc  when  a  window  is  first  being  created.  Windows  calls 
WndProc  when  the  window  is  later  destroyed.  Windows  calls  WndProc  when  the  window 
has  been  resized  or  moved  or  made  into  an  icon.  Windows  calls  WndProc  when  an  item 
has  been  selected  from  a  menu.  Windows  calls  WndProc  when  a  scroll  bar  is  manipulated 
or  clicked  with  the  mouse.  Windows  calls  WndProc  to  tell  it  when  it  must  repaint  its 
client  area. 

All  these  calls  are  in  the  form  of  messages.  In  most  Windows  programs,  the  bulk  of 
the  program  is  dedicated  to  handling  these  messages.  The  140  or  so  different  messages  that 
Windows  can  send  to  a  window  procedure  are  all  identified  with  names  that  begin  with  the 
letters  WM  and  are  defined  in  WINDOWS.H. 

Actually,  the  idea  of  a  routine  within  a  program  that  is  called  from  outside  the 
program  is  not  unheard  of  in  normal  programming.  The  signal  function  in  C  can  trap  a 
Ctrl-Break.  You  may  have  experience  with  intercepting  hardware  interrupts  in  assembly 
language  or  using  one  of  the  ON  constructions  in  Microsoft  BASIC.  The  Microsoft  Mouse 
driver  has  a  method  that  non-Windows  programs  can  use  to  be  notified  of  mouse  activity. 

In  Windows,  this  concept  is  extended  to  cover  everything.  Everything  that  happens 
to  a  window  is  relayed  to  the  window  procedure  in  the  form  of  a  message.  The  window 
procedure  then  responds  to  this  message  in  some  way  or  passes  the  message  to  DefWin- 
dowProc  for  default  processing. 

The  wParam  and  iParam  parameters  to  the  window  procedure  are  not  used  in 
HELLOWIN  except  as  parameters  to  DefWindowProc .  These  parameters  give  the  window 
procedure  additional  information  about  the  message.  The  meaning  of  the  parameters  is 
message-dependent. 

Let’s  look  at  an  example.  Whenever  the  client  area  of  a  window  changes  in  size,  Win¬ 
dows  calls  that  window’s  window  procedure.  The  hwnd  parameter  to  the  window  pro¬ 
cedure  is  the  handle  of  the  window  changing  in  size.  The  message  parameter  is  WM-SIZE. 
The  wParam  parameter  for  a  WM-SIZE  message  is  the  value  SIZENORMAL,  SIZEICONIC, 
SIZEFULLSCREEN,  SIZEZOOMSHOW,  or  SIZEZOOMHIDE  (defined  in  WINDOWS.H  as 
the  numbers  0  through  4).  The  wParam  parameter  indicates  whether  the  window  is  being 
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minimized,  maximized,  or  hidden  (as  a  result  of  another  window  being  maximized).  The 
IParam  parameter  contains  the  new  size  of  the  window.  The  new  width  (a  16-bit  value) 
and  the  new  height  (a  16-bit  value)  have  been  stuck  together  in  the  32-byte  IParam . 
WINDOWS.H  includes  macros  to  help  you  extract  these  two  values  from  IParam.  We’ll 
do  this  in  the  next  chapter. 

Sometimes  messages  generate  other  messages  as  a  result  of  DefWindowProc  pro¬ 
cessing.  For  example,  suppose  you  run  HELLOWIN  and  select  Close  from  the  system 
menu  using  either  the  keyboard  or  the  mouse.  DefWindowProc  processes  this  keyboard 
and  mouse  input.  When  it  detects  that  you  have  selected  the  Close  option,  it  sends  a 
WM-SYSCOMMAND  message  to  the  window  procedure.  WndProc  passes  this  message  to 
DefWindowProc.  DefWindowProc  responds  by  sending  a  WM -CLOSE  message  to  the 
window  procedure.  WndProc  again  passes  this  message  to  DefWindowProc.  DefWindow¬ 
Proc  responds  to  the  WM -CLOSE  message  by  calling  DestroyWindow.  DestroyWindow 
causes  Windows  to  send  a  WM -DESTROY  message  to  the  window  procedure.  WndProc 
finally  responds  to  this  message  by  calling  PostQuit Message X.o  put  a  WM-QUIT  message  in 
the  message  queue.  This  message  causes  the  message  loop  in  WinMain  to  terminate  and 
the  program  to  end. 

Queued  and  Nonqueued  Messages 

I’ve  talked  about  Windows  sending  messages  to  a  window,  which  means  that  Windows 
calls  the  window  procedure.  But  a  Windows  program  also  has  a  message  loop  that 
retrieves  messages  from  a  message  queue  by  calling  GetMessage  and  dispatches  them  to 
the  window  procedure  by  calling  DispatchMessage. 

So,  does  a  Windows  program  poll  for  messages  (exactly  as  a  normal  program  polls 
for  keyboard  data)  and  then  route  these  messages  to  some  location?  Or  does  it  receive  mes¬ 
sages  directly  from  outside  the  program?  Well,  both. 

Messages  can  be  either  “queued”  or  “nonqueued.”  The  queued  messages  are  those 
that  are  placed  in  a  program’s  message  queue  by  Windows  and  retrieved  and  dispatched  in 
the  message  loop.  The  nonqueued  messages  are  sent  to  the  window  directly  when  Win¬ 
dows  calls  the  window  procedure.  The  result  is  that  the  window  procedure  gets  all  the 
messages — both  queued  and  nonqueued — for  the  window.  Structurally,  Windows  pro¬ 
grams  are  very  clean  because  they  have  one  central  point  of  message  processing.  It  is  said 
that  queued  messages  are  posted  to  a  message  queue  while  nonqueued  messages  are  sent 
to  the  window  procedure. 

The  queued  messages  are  primarily  those  that  result  from  user  input  in  the  form  of 
keystrokes  (such  as  WM-KEYDOWN  and  WM-KEYUP),  characters  that  result  from 
keystrokes  (WM-CHAR),  mouse  movement  (WM-MOUSEMOVE),  and  mouse  button 
clicks  (WM-LBUTTONDOWN).  Queued  messages  also  include  the  timer  message 
(WM-TIMER),  the  repaint  message  (WM-PAINT),  and  the  quit  message  (WM-QUIT). 
The  nonqueued  messages  are  everything  else.  In  many  cases  the  nonqueued  messages 
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result  from  queued  messages.  When  you  pass  a  nonqueued  message  to  DefWindowProc 
within  the  window  procedure,  Windows  often  processes  the  message  by  sending  the 
window  procedure  other  messages. 

This  process  is  obviously  complex,  but  fortunately  most  of  the  complexity  is  Win¬ 
dows’  problem  rather  than  our  program’s.  From  the  perspective  of  the  window  procedure, 
these  messages  come  through  in  an  orderly,  synchronized  manner.  The  window  procedure 
can  do  something  with  these  messages  or  ignore  them.  For  this  reason,  the  window  pro¬ 
cedure  has  been  called  the  “ultimate  hook.”  Messages  notify  the  window  procedure  of 
almost  everything  that  affects  the  window. 

The  nonqueued  messages  often  result  from  calling  certain  Windows  function  calls  or 
from  explicitly  sending  a  message  by  calling  SendMessage .  (Messages  can  also  be  placed  in 
a  message  queue  by  calling  Post  Message.) 

For  example,  when  WinMain  calls  CreateWindow ,  Windows  creates  the  window  and 
in  the  process  sends  the  window  procedure  a  WM -CREATE  message.  When  WinMain 
calls  ShowWindow,  Windows  sends  the  window  procedure  WM-SIZE  and  WM-SHOW- 
WINDOW  messages.  When  WinMain  calls  UpdateWindow,  Windows  sends  the  window 
procedure  a  WM -PAINT  message. 

Messages  are  not  like  hardware  interrupts.  While  processing  one  message  in  a  win¬ 
dow  procedure,  the  program  will  not  be  interrupted  by  another  message.  Only  when  the 
window  procedure  calls  a  function  that  generates  a  new  message  will  the  message  pro¬ 
cedure  process  the  message  before  the  function  returns. 

The  message  loop  and  the  window  procedure  do  not  run  concurrently.  When  the 
window  procedure  is  processing  a  queued  message,  it  is  the  result  of  a  call  to  Dis- 
patchMessage  in  WinMain.  DispatchMessage  does  not  return  until  the  window  procedure 
has  processed  the  message. 

But  notice  that  the  window  procedure  must  be  reentrant.  That  is,  Windows  often 
calls  WndProc  with  a  new  message  as  a  result  of  WndProc  calling  DefWindowProc  with  a 
previous  message.  This  is  one  reason  that  a  Windows  program  requires  an  8-KB  stack,  as 
indicated  in  the  module  definition  (.DEF)  file.  In  most  cases  the  reentrancy  of  the  window 
procedure  presents  no  problem,  but  you  should  be  aware  of  it. 

In  many  cases,  the  window  procedure  must  retain  information  it  obtains  in  one  mes¬ 
sage  and  use  it  while  processing  another  message.  This  information  must  be  saved  in  vari¬ 
ables  defined  as  static  in  the  window  procedure  or  in  global  variables. 

Of  course,  you’ll  get  a  much  better  feel  for  all  this  in  later  chapters  as  the  window 
procedures  are  expanded  to  process  more  messages. 

Nonpreemptive  Multitasking 

The  GetMessage  call  within  the  message  loop  is  important  for  another  reason.  Except  for 
some  device  drivers  that  must  process  hardware  interrupts  (such  as  the  timer,  keyboard, 
mouse,  and  serial  port),  Windows  usually  treats  HELLOWIN  as  if  it  were  the  only  program 
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running  under  the  system.  Windows  will  not  arbitrarily  switch  away  from  HELLOWIN  and 
run  some  other  program.  The  exception  is  during  the  GetMessage  call.  If  HELLOWIN’s 
message  queue  has  no  waiting  messages  and  another  program  has  some  messages  in  its 
message  queue,  then  Windows  switches  from  HELLOWIN  to  the  other  program.  That 
makes  sense,  does  it  not? 

You  can  think  of  it  this  way:  In  most  cases,  when  your  program  calls  a  function  in 
Windows,  you  can  expect  that  the  function  will  be  processed  and  return  control  to  your 
program  within  a  reasonable  period  of  time.  When  you  call  GetMessage ,  however,  it  may 
be  some  time  before  Windows  returns  with  a  message  if  the  program’s  message  queue 
does  not  contain  any  messages  and  another  program’s  message  queue  does.  Windows  can 
take  advantage  of  the  delay  caused  by  an  empty  message  queue  during  a  GetMessage  call  to 
switch  to  another  program  that  has  messages  waiting.  As  a  result,  Windows  has  a  “jumpy” 
type  of  multitasking.  Sometimes  a  program  has  a  long  job  to  do,  and  all  other  programs 
running  under  Windows  seem  to  stop  running  during  this  time. 

Rather  than  “jumpy  multitasking,”  this  characteristic  is  usually  called  “nonpreemp- 
tive  multitasking.”  Windows  is  multitasking  between  programs  by  switching  between 
them.  But  Windows  is  not  doing  this  as  it  is  done  within  a  traditional  multitasking  system, 
based  on  the  tick  of  a  hardware  clock  and  allocating  each  program  a  tiny  time-slice  to  do 
its  stuff.  Windows  multitasks  at  the  point  where  programs  check  the  message  queue  for 
messages. 

The  process  is  actually  a  little  more  complex  than  that:  Windows  also  switches  be¬ 
tween  programs  during  PeekMessage  and  WaitMessage  calls,  but  these  are  less  common 
than  GetMessage .  Furthermore,  the  WM_PAINT  and  WM_TIMER  messages  are  treated  as 
low-priority  messages,  so  Windows  can  switch  from  a  program  if  only  WM -PAINT  and 
WM -TIMER  messages  are  present  in  the  queue. 

The  Learning  Curve 

Yes,  as  you’ve  undoubtedly  determined  from  this  chapter,  Windows  programming  is  cer¬ 
tainly  different  from  programming  for  a  conventional  environment  like  MS-DOS.  Nobody 
will  claim  that  Windows  programming  is  easy. 

When  I  first  started  learning  Windows  programming,  I  decided  to  do  what  I  had 
always  done  when  learning  a  new  operating  system  or  a  new  language — write  a  simple 
“hex  dump”  program  to  display  the  contents  of  a  file.  In  the  conventional  MS-DOS 
environment,  such  a  program  involves  command-line  processing,  rudimentary  file  I/O, 
and  screen  output  formatting.  However,  my  Windows  hex-dump  program  turned  into  a 
monster.  It  required  that  I  learn  about  menus,  dialog  boxes,  scroll  bars,  and  the  like.  As 
a  first  Windows  program,  it  was  definitely  a  mistake,  demanding  that  I  absorb  too  much 
all  at  once. 
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Yet  when  this  program  was  finished,  it  was  quite  unlike  any  hex-dump  program  I  had 
ever  written.  Rather  than  obtain  the  filename  from  a  command  line,  WINDUMP  (as  I  called 
it)  presented  a  list  box  showing  all  the  files  in  the  current  directory.  Rather  than  write  its 
output  to  the  screen  in  a  simple  teletype  fashion,  WINDUMP  had  scroll  bars  so  I  could 
move  to  any  part  of  the  file.  As  an  extra  bonus,  I  could  even  run  two  copies  of  WINDUMP 
to  compare  two  files  side  by  side.  In  short,  WINDUMP  was  the  first  hex- dump  program  I 
wrote  that  I  was  actually  proud  of. 

What  you  have  to  ask  yourself  is  this:  Do  I  want  my  programs  to  use  a  more  modern 
and  productive  user  interface,  one  that  includes  menus,  dialog  boxes,  scroll  bars,  and 
graphics?  If  you  answer  yes,  then  the  question  becomes:  Do  I  want  to  write  all  this  menu, 
dialog  box,  scroll  bar,  and  graphics  code  myself?  Or  would  I  rather  take  advantage  of  all  the 
code  already  inside  Windows  for  this?  In  other  words,  is  it  easier  to  learn  how  to  use  1000 
function  calls  or  to  write  them  yourself?  Is  it  easier  to  orient  your  programming  mind  to  the 
message-driven  architecture  of  Windows  or  struggle  with  using  several  different  sources  of 
user  input  in  a  traditional  model? 

If  you’re  going  to  write  your  own  user  interface  logic,  you  had  better  close  this  book 
and  get  to  work  right  away.  Meanwhile,  the  rest  of  us  are  going  to  learn  how  to  display  and 
scroll  text  in  a  window. 
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Painting 
with  Text 


In  the  previous  chapter,  you  saw  a  simple  Windows  program  that  displayed  a  single  line  of 
text  in  the  center  of  its  client  area.  The  client  area  occupies  all  the  space  of  the  window 
that  is  not  taken  up  by  the  caption  bar,  the  window-sizing  border,  the  menu  bar  (if  any),  and 
scroll  bars  (if  any).  The  client  area  is  the  part  of  the  window  on  which  a  program  is  free  to 
draw.  You  can  do  almost  anything  you  want  with  that  client  area — anything,  that  is,  except 
assume  that  it  will  be  a  particular  size  or  that  the  size  will  remain  constant  while  your  pro¬ 
gram  is  running.  If  you  are  accustomed  to  writing  programs  for  the  IBM  PC,  these  excep¬ 
tions  may  come  as  a  bit  of  a  shock.  You  can  no  longer  think  in  terms  of  25  lines  and  80 
columns  of  text.  Your  program  shares  the  video  display  with  other  Windows  programs. 
The  user  controls  how  the  programs  are  arranged  on  the  screen.  Your  program  must  ac¬ 
cept  the  size  it’s  given  and  do  something  reasonable  with  it.  (A  program  could  create  a 
window  of  a  specific  fixed  size,  but  it  isn’t  very  common.) 

This  works  both  ways.  Just  as  your  program  may  find  itself  with  a  client  area  barely 
large  enough  in  which  to  say  “Hello,”  it  may  also  someday  be  run  on  a  big-screen,  high- 
resolution  video  system  and  discover  a  client  area  large  enough  for  two  entire  pages  of  text 
and  plenty  of  closet  space  besides.  Dealing  intelligently  with  both  eventualities  is  an  im¬ 
portant  part  of  Windows  programming. 

Although  Windows  has  extensive  Graphics  Device  Interface  (GDI)  functions  for  dis¬ 
playing  graphics,  in  this  chapter  I’ll  stick  to  displaying  simple  lines  of  text.  I’ll  also  ignore 
the  various  fonts  (typefaces)  and  font  sizes  that  Windows  makes  available  and  use  only 
Windows’  default  “system  font.”  This  may  seem  limiting,  but  it  really  isn’t.  The  problems 
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we  encounter — and  solve — in  this  chapter  apply  to  all  Windows  programming.  When  you 
display  a  combination  of  text  and  graphics  (as,  for  instance,  the  Windows  CALENDAR, 
CARDFILE,  and  CALCULATOR  programs  do),  the  character  dimensions  of  Windows’ 
default  system  font  often  determine  the  dimensions  of  the  graphics. 

This  chapter  is  ostensibly  about  learning  how  to  paint,  but  it’s  really  about  learning 
the  basics  of  device-independent  programming.  Windows  programs  can  assume  little 
about  their  environment.  Instead,  they  must  use  the  facilities  that  Windows  provides  to 
obtain  information  about  the  environment. 


PAINTING  AND  REPAINTING 

Under  MS-DOS,  a  program  using  the  display  in  a  full-screen  mode  can  write  to  any  part  of 
the  display.  What  the  program  puts  on  the  display  will  stay  there  and  will  not  mysteriously 
disappear.  The  program  can  then  discard  information  needed  to  re-create  the  screen  dis¬ 
play.  If  another  program  (such  as  a  RAM-resident  popup)  overlays  part  of  the  display,  then 
the  popup  is  responsible  for  restoring  the  display  when  it  leaves. 

In  Windows,  you  can  display  only  in  the  client  area  of  your  window,  and  you  cannot 
be  assured  that  what  you  display  in  the  client  area  will  remain  there  until  your  program 
specifically  writes  over  it.  For  instance,  the  dialog  box  from  another  application  may 
overlay  part  of  your  client  area.  Although  Windows  will  attempt  to  save  and  restore  the 
area  of  the  display  underneath  the  dialog  box,  it  sometimes  cannot  do  so.  When  the  dialog 
box  is  removed  from  the  screen,  Windows  will  request  that  your  program  repaint  this 
portion  of  your  client  area. 

Windows  is  a  message-driven  system.  Windows  informs  applications  of  various 
events  by  posting  messages  in  the  application’s  message  queue  or  sending  messages  to  the 
appropriate  window  procedure.  Windows  informs  a  window  procedure  that  part  of  the 
window’s  client  area  needs  updating  by  posting  a  WM-PAINT  message. 

The  WM.PAINT  Message 

Most  Windows  programs  call  the  function  UpdateWindow  during  initialization  in  Win- 
Main  shortly  before  entering  the  message  loop.  Windows  takes  this  opportunity  to  send 
the  window  procedure  its  first  WM_PAINT  message.  That  message  informs  your  window 
procedure  that  the  client  area  is  ready  to  be  painted.  Thereafter,  that  window  procedure 
should  be  ready  at  any  time  to  process  additional  WM-PAINT  messages  and  even  to  re¬ 
paint  the  entire  client  area  of  the  window  if  necessary.  A  window  procedure  receives  a 
WM_PAINT  message  whenever  one  of  the  following  occurs: 

■  A  previously  hidden  area  of  the  window  is  brought  into  view  when  a  user 
moves  a  window  or  uncovers  a  window. 

■  The  user  resizes  the  window  (if  the  window  class  style  has  the  CS- 
-HREDRAW  and  CS-VREDRAW  bits  set). 
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■  The  program  uses  the  ScrollWindow  or  ScrollDC  function  to  scroll  part 
of  its  client  area. 

■  The  program  uses  the  InvalidateRect  or  InvalidateRgn  function  to  ex¬ 
plicitly  generate  a  WM_PAINT  message. 

In  some  cases  in  which  part  of  the  client  area  is  temporarily  written  over,  Windows 
attempts  to  save  an  area  of  the  display  and  restore  it  later.  This  is  not  always  successful. 
Windows  may  sometimes  post  a  WM-PAINT  message  when: 

■  Windows  removes  a  dialog  box  or  message  box  that  was  overlaying  part  of 
the  window. 

■  A  menu  is  pulled  down  and  then  released. 

In  a  few  cases,  Windows  always  saves  the  area  of  the  display  it  overwrites  and  then 
restores  it.  This  is  the  case  whenever: 

■  The  cursor  is  moved  across  the  client  area. 

■  An  icon  is  dragged  across  the  client  area. 

Dealing  with  WM_PAINT  messages  requires  that  you  alter  your  thinking  about  how 
you  write  to  the  display.  Your  program  should  be  structured  so  that  it  accumulates  all  the 
information  necessary  to  paint  the  client  area  but  paints  only  “on  demand” — when  Win¬ 
dows  sends  the  window  procedure  a  WM_PAINT  message.  If  your  program  needs  to 
update  its  client  area,  it  can  force  Windows  to  generate  this  WM -PAINT  message.  This 
may  seem  a  roundabout  method  of  displaying  something  on  the  screen,  but  the  structure 
of  your  program  will  benefit  from  it. 

Valid  and  Invalid  Rectangles 

Although  a  window  procedure  should  be  prepared  to  update  the  entire  client  area  when¬ 
ever  it  receives  a  WM_PAINT  message,  it  often  needs  to  update  only  a  smaller  area  (most 
often  a  rectangular  area  within  the  client  area).  This  is  most  obvious  when  part  of  the  cli¬ 
ent  area  is  overlaid  by  a  dialog  box.  Repainting  is  required  only  for  the  rectangular  area  un¬ 
covered  when  the  dialog  box  is  removed. 

That  area  is  known  as  an  “invalid  region”  or  “update  region.”  The  presence  of  an  in¬ 
valid  region  in  a  client  area  is  what  prompts  Windows  to  place  a  WM_PAINT  message  in 
the  application’s  message  queue.  Your  window  procedure  receives  a  WM_PAINT  message 
only  if  part  of  your  client  area  is  invalid. 

Windows  internally  maintains  a  “paint  information  structure”  for  each  window.  This 
structure  contains  (among  other  information)  the  coordinates  of  the  smallest  rectangle  that 
encompasses  the  invalid  region.  This  is  known  as  the  “invalid  rectangle”;  sometimes  it  is 
also  called  the  “invalid  region.”  If  another  region  of  the  client  area  becomes  invalid  before 
the  window  procedure  processes  the  WM -PAINT  message,  Windows  calculates  a  new 
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invalid  region  that  encompasses  both  areas  and  stores  this  updated  information  in  the 
paint  information  structure.  Windows  does  not  place  multiple  WM-PAINT  messages  in  the 
message  queue. 

A  window  procedure  can  invalidate  a  rectangle  in  its  own  client  area  by  calling 
InvalidateRect .  If  the  message  queue  already  contains  a  WM_PAINT  message,  Windows 
calculates  a  new  invalid  rectangle.  Otherwise,  it  places  a  new  WM_PAINT  message  in  the 
message  queue.  A  window  procedure  can  obtain  the  coordinates  of  the  invalid  rectangle 
when  it  receives  a  WM -PAINT  message  (as  we’ll  see  shortly).  It  can  also  obtain  these  coor¬ 
dinates  at  any  other  time  by  calling  GetUpdateRect . 

After  the  window  procedure  calls  BeginPaint  during  the  WM-PAINT  message,  the 
entire  client  area  is  validated.  A  program  can  also  validate  any  rectangular  region  in  the 
client  area  by  calling  the  ValidateRect  function.  If  this  call  has  the  effect  of  validating 
the  entire  invalid  area,  then  any  WM_PAINT  message  currently  in  the  queue  is  deleted. 

AN  INTRODUCTION  TO  GDI 

To  paint  the  client  area  of  your  window,  you  use  Windows’  Graphics  Device  Interface 
(GDI)  functions.  (A  full  discussion  of  GDI  is  in  Chapters  11  through  15.)  Windows  provides 
five  GDI  functions  for  writing  text  strings  to  the  client  area  of  the  window.  We’ve  already 
encountered  the  DrawText  function  in  Chapter  1,  but  the  most  popular  text  output  func¬ 
tion  by  far  is  TextOut.  This  function  has  the  following  format: 

TextOut  (hdc,  x,  y,  IpsString,  nLength)  ; 

TextOut  writes  a  character  string  to  the  display.  The  IpsString  parameter  is  a  long  (or  far) 
pointer  to  the  character  string,  and  nLength  is  the  length  of  the  string.  The  x  and  y  param¬ 
eters  define  the  starting  position,  in  “logical  coordinates,”  of  the  character  string  in 
the  client  area.  The  hdc  parameter  is  a  “handle  to  a  device  context,”  and  it  is  an  important 
part  of  GDI.  Virtually  every  GDI  function  requires  this  handle  as  the  first  parameter  to 
the  function. 

The  Device  Context 

A  handle,  you’ll  recall,  is  simply  a  number  that  Windows  uses  for  internal  reference  to  an 
object.  You  obtain  the  handle  from  Windows  and  then  use  the  handle  in  other  functions. 
The  device  context  handle  is  your  window’s  passport  to  the  GDI  functions.  With  that 
device  context  handle  you  are  free  to  paint  your  client  area  and  make  it  as  beautiful  or  as 
ugly  as  you  like. 

The  device  context  (also  called  the  “DC”)  is  really  a  data  structure  maintained  by 
GDI.  A  device  context  is  associated  with  a  particular  display  device,  such  as  a  printer,  plot¬ 
ter,  or  video  display.  For  a  video  display,  a  device  context  is  usually  associated  with  a 
particular  window  on  the  display. 
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Windows  uses  the  values  in  the  device  context  structure  (also  called  “attributes”  of 
the  device  context)  in  conjunction  with  the  GDI  functions.  With  TextOut,  for  instance,  the 
attributes  of  the  device  context  determine  the  color  of  the  text,  the  color  of  the  text  back¬ 
ground,  how  the  ^-coordinate  and  ^-coordinate  are  mapped  to  the  client  area  of  the 
window,  and  what  font  Windows  uses  when  displaying  the  text. 

When  a  program  needs  to  paint,  it  must  first  obtain  a  handle  to  a  device  context.  After 
it  has  finished  painting,  the  program  should  release  the  handle.  When  a  program  releases 
the  handle,  the  handle  is  no  longer  valid  and  must  not  be  used.  The  program  should  obtain 
the  handle  and  release  the  handle  during  processing  of  a  single  message.  Except  for  a  de¬ 
vice  context  created  with  a  call  to  CreateDC,  you  should  not  keep  a  device  context  handle 
around  from  one  message  to  another. 

Windows  applications  generally  use  two  methods  for  getting  a  device  context  handle 
in  preparation  for  painting  the  screen. 

Getting  a  Device  Context  Handle:  Method  One 

You  use  this  method  when  you  process  WM_PAINT  messages.  Two  functions  are  involved: 
BeginPaint  and  EndPaint.  These  two  functions  require  the  handle  to  the  window  (passed 
to  the  window  procedure  as  a  parameter)  and  the  address  of  a  structure  variable  of  type 
PAINTSTRUCT.  Windows  programmers  usually  name  this  structure  variable  ps  and  define 
it  within  the  window  procedure,  like  so: 

PAINTSTRUCT  ps  ; 

While  processing  a  WM_PAINT  message,  a  Windows  function  first  calls  BeginPaint 
to  fill  in  the  fields  of  the  ps  structure.  The  value  returned  from  BeginPaint  is  the  device 
context  handle.  This  is  commonly  saved  in  a  variable  named  hdc.  You  define  this  variable 
in  your  window  procedure  like  this: 

HDC  hdc  ; 

The  HDC  data  type  is  defined  in  WINDOWS.H  as  a  HANDLE,  which  is  a  16-bit  unsigned 
integer.  The  program  may  then  use  GDI  functions  such  as  TextOut.  A  call  to  EndPaint 
releases  the  device  context  handle. 

Typically,  processing  of  the  WM_PAINT  message  looks  like  this: 

case  WM_PA I  NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

[use  GDI functions] 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

The  window  procedure  must  call  BeginPaint  and  EndPaint  as  a  pair  while  processing  the 
WM_PAINT  message.  If  a  window  procedure  does  not  process  WM_PAINT  messages, 
then  it  must  pass  the  WM-PAINT  message  to  DefWindowProc  (the  default  window  pro¬ 
cedure)  located  in  Windows. 
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DefWindowProc  processes  WM-PAINT  messages  with  the  following  code: 

case  WM.PAINT  : 

BeginPaint  (hwnd,  &ps)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

This  sequence  of  BeginPaint  and  EndPaint  with  nothing  in  between  simply  validates  the 
previously  invalid  region.  But  don’t  do  this: 

case  WM_PAI NT  : 

return  0  ;  //  WRONG  ! ! ! 

Windows  places  a  WM_PAINT  message  in  the  message  queue  because  part  of  the  client 
area  is  invalid.  Unless  you  call  BeginPaint  and  EndPaint  {or  ValidateRect ),  Windows  will 
not  validate  that  area.  Instead,  Windows  will  send  you  another  WM_PAINT  message.  And 
another,  and  another,  and  another . . . 

The  Paint  Information  Structure 

Earlier  I  mentioned  a  “paint  information  structure”  that  Windows  maintains  for  each  win¬ 
dow.  That’s  what  PAINTSTRUCT  is.  The  structure  is  defined  in  WINDOWS.H  as  follows: 

typedef  struct  tagPAI NTSTRUCT 
{ 

HDC  hdc  ; 

BOOL  fErase  ; 

RECT  rcPaint  ; 

BOOL  fRestore  ; 

BOOL  flncUpdate  ; 

BYTE  rgbReserved[16]  ; 

} 

PAINTSTRUCT  ; 

Windows  fills  in  the  fields  of  this  structure  when  your  program  calls  BeginPaint. 
Your  program  may  use  only  the  first  three  fields.  The  others  are  used  internally  by 
Windows. 

The  hdc  field  is  the  handle  to  the  device  context.  In  a  redundancy  typical  of  Win¬ 
dows,  the  value  returned  from  BeginPaint  is  also  this  device  context  handle. 

In  most  cases,  fErase  will  be  flagged  TRUE  (nonzero),  meaning  that  Windows  has 
erased  the  background  of  the  invalid  rectangle.  Windows  erases  the  background  using  the 
brush  specified  in  the  hbrBackground  field  of  the  WNDCLASS  structure  that  you  use 
when  registering  the  window  class  during  WinMain  initialization.  Many  Windows  pro¬ 
grams  use  a  white  brush: 

wndclass. hbrBackground  =  GetStockObject  ( WH I TE_B RUSH )  ; 

However,  if  your  program  invalidates  a  rectangle  of  the  client  area  by  calling  the 
Windows  function  InvalidateRect ,  one  of  the  parameters  of  this  function  specifies  whether 
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you  want  the  background  erased.  If  this  parameter  is  FALSE  (or  0),  then  Windows  will  not 
erase  the  background,  and  the  /Erase  field  will  also  be  FALSE. 

The  rcPaint  field  of  the  PAINTSTRUCT  structure  is  a  structure  of  type  RECT.  As  you 
learned  in  Chapter  1,  the  RECT  structure  defines  a  rectangle.  The  four  fields  are  left ,  top , 
right ,  and  bottom.  The  rcPaint  field  in  the  PAINTSTRUCT  structure  defines  the  bound¬ 
aries  of  the  invalid  rectangle,  as  shown  in  Figure  2-1.  The  values  are  in  units  of  pixels  rela¬ 
tive  to  the  upper  left  corner  of  the  client  area.  The  invalid  rectangle  is  the  area  that  you 
should  repaint.  Although  a  Windows  program  can  simply  repaint  the  entire  client  area  of 
the  window  whenever  it  receives  a  WM -PAINT  message,  repainting  only  the  area  of  the 
window  defined  by  that  rectangle  saves  time. 
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Figure  2-1 .  The  boundaries  of  the  invalid  rectangle. 

The  rcPaint  rectangle  in  PAINTSTRUCT  is  not  only  the  invalid  rectangle;  it  is  also  a 
“clipping”  rectangle.  This  means  that  Windows  restricts  painting  to  within  the  clipping 
rectangle.  (More  precisely,  if  the  invalid  region  is  not  rectangular,  Windows  restricts 
painting  to  within  that  region.)  When  you  use  the  device  context  handle  from  the 
PAINTSTRUCT  structure,  Windows  will  not  paint  outside  the  rcPaint  rectangle. 

To  paint  outside  this  rcPaint  rectangle  while  processing  WM -PAINT  messages,  you 
can  make  this  call: 

Inval idateRect  (hWnd,  NULL,  TRUE)  ; 
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before  calling  BeginPaint.  This  invalidates  the  entire  client  area  and  erases  the  back¬ 
ground.  A  FALSE  value  in  the  last  parameter  will  not  erase  the  background,  however. 
Whatever  was  there  will  stay. 

In  the  HELLOWIN  program  in  Chapter  1,  we  didn’t  care  about  invalid  rectangles  or 
clipping  rectangles  when  processing  the  WM_PAINT  message.  If  the  area  where  the  text 
was  displayed  happened  to  be  within  the  invalid  rectangle,  then  DrawText  restored  it.  If 
not,  then  at  some  point  during  processing  of  the  DrawText  call,  Windows  determined  it 
didn’t  have  to  write  anything  to  the  display.  But  this  determination  takes  time.  A  program¬ 
mer  concerned  about  performance  and  speed  will  want  to  use  the  invalid-rectangle 
dimensions  during  processing  of  WM_PAINT  to  avoid  unnecessary  GDI  calls. 

Getting  a  Device  Context  Handle:  Method  Two 

You  can  also  obtain  a  handle  to  a  device  context  if  you  want  to  paint  the  client  area  when 
processing  messages  other  than  WM_PAINT  or  if  you  need  the  device  context  handle  for 
other  purposes,  such  as  obtaining  information  about  the  device  context.  Call  GetDC  to  ob¬ 
tain  the  handle  to  the  device  context,  and  call  ReleaseDC  after  you’re  done  with  it: 

hdc  =  GetDC  (hwnd)  ; 

[use  GDI functions] 

ReleaseDC  (hwnd.  hdc)  ; 

Like  BeginPaint  and  EndPaint ,  the  GetDC  and  ReleaseDC  functions  should  be  called  in 
pairs.  When  you  call  GetDC  while  processing  a  message,  you  should  call  ReleaseDC  before 
you  exit  the  window  procedure.  Do  not  call  GetDC  in  response  to  one  message  and 
ReleaseDC  in  response  to  another. 

Unlike  the  device  context  handle  obtained  from  the  PAINTSTRUCT  structure,  the  de¬ 
vice  context  handle  returned  from  GetDC  has  a  clipping  rectangle  equal  to  the  entire  client 
area.  You  can  paint  on  any  part  of  the  client  area,  not  merely  on  the  invalid  rectangle  (if 
indeed  there  is  an  invalid  rectangle).  Unlike  BeginPaint ,  GetDC  does  not  validate  any  in¬ 
valid  regions. 

TextOut:  The  Details 

When  you  obtain  the  handle  to  the  device  context,  Windows  fills  the  device  context  struc¬ 
ture  with  default  values.  As  you’ll  see  in  later  chapters,  you  can  change  these  defaults  with 
GDI  functions.  The  GDI  function  we’re  interested  in  right  now  is  TextOut : 

TextOut  (hdc,  x,  y,  IpsString,  nLength)  ; 

Let’s  examine  this  function  in  more  detail. 

The  first  parameter  is  the  handle  to  the  device  context — either  the  hdc  value 
returned  from  GetDC  or  the  hdc  value  returned  from  BeginPaint  during  processing  of  a 
WM_PAINT  message. 
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The  attributes  of  the  device  context  control  the  characteristics  of  this  displayed  text. 
For  instance,  one  attribute  of  the  device  context  specifies  the  text  color.  The  default  color  is 
black.  The  default  device  context  also  defines  a  background  color  of  white.  When  a  pro¬ 
gram  writes  text  to  the  display,  Windows  uses  this  background  color  to  fill  in  the  space 
surrounding  the  characters. 

This  text  background  color  is  not  the  same  background  you  set  when  defining  the 
window  class.  The  background  in  the  window  class  is  a  brush — which  is  a  pattern  that 
may  or  may  not  be  a  pure  color — that  Windows  uses  to  erase  the  client  area.  It  is  not  part 
of  the  device  context  structure.  When  defining  the  window  class  structure,  most  Windows 
applications  use  WHITE_BRUSH  so  that  the  background  color  in  the  default  device  con¬ 
text  is  the  same  color  as  the  brush  Windows  uses  to  erase  the  background  of  the  client  area. 

The  IpsString  parameter  is  a  long  pointer  to  a  character  string,  and  nLength  is  the 
length  of  the  string.  The  string  should  not  contain  any  ASCII  control  characters  such  as  car¬ 
riage  returns,  linefeeds,  tabs,  or  backspaces.  Windows  displays  these  control  characters  as 
solid  blocks.  TextOut  does  not  recognize  a  0  as  denoting  the  end  of  a  string  and  requires 
the  nLength  parameter  for  the  length. 

The  x  and  y  values  in  TextOut  define  the  starting  point  of  the  character  string  within 
the  client  area.  The  x  value  is  the  horizontal  position;  the  y  value  is  the  vertical  position. 
The  upper  left  corner  of  the  first  character  in  the  string  is  positioned  at  the  coordinate  point 
(x,  y ).  In  the  default  device  context,  the  origin  (the  point  where  x  and  y  both  equal  0)  is  the 
upper  left  corner  of  the  client  area.  If  you  use  0  values  for  x  and  y  in  TextOut ,  the  character 
string  starts  flush  against  the  upper  left  corner  of  the  client  area. 

GDI  coordinates  are  “logical  coordinates.”  Windows  has  a  variety  of  “mapping 
modes”  that  govern  how  the  logical  coordinates  specified  in  GDI  functions  are  translated 
to  the  physical  pixel  coordinates  of  the  display.  The  mapping  mode  is  defined  in  the  device 
context.  The  default  mapping  mode  is  called  MM_TEXT  (using  the  WINDOWS.H  iden¬ 
tifier).  Under  the  MM_TEXT  mapping  mode,  logical  units  are  the  same  as  physical  units, 
which  are  pixels.  Values  of  x  increase  as  you  move  to  the  right  in  the  client  area,  and  values 
of  y  increase  as  you  move  down  in  the  client  area.  (See  Figure  2-2  on  the  following  page.) 
The  MM _TEXT  coordinate  system  is  identical  to  the  coordinate  system  that  Windows  uses 
to  define  the  invalid  rectangle  in  the  PAINTSTRUCT  structure.  Very  convenient.  (This  is 
not  the  case  with  other  mapping  modes,  however.) 

The  device  context  also  defines  a  clipping  region.  As  you’ve  seen,  the  default  clip¬ 
ping  region  is  the  entire  client  area  for  a  device  context  handle  obtained  from  GetDC  and 
the  invalid  region  for  the  device  context  handle  obtained  from  BeginPaint.  Windows  will 
not  display  any  part  of  the  character  string  that  lies  outside  the  clipping  region.  If  a  charac¬ 
ter  is  partly  within  the  clipping  region,  Windows  displays  only  the  portion  of  the  character 
inside  the  region.  Writing  outside  the  client  area  of  your  window  isn’t  easy  to  do,  so  don’t 
worry  about  doing  it  inadvertently. 
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Figure  2-2.  The  x-coordinate  and  y-coordinate  in  the  MM -TEXT  mapping  mode. 

The  System  Font 

The  device  context  also  defines  the  font  that  Windows  uses  when  writing  text  to  the  client 
area.  The  default  is  a  font  called  the  “system  font”  or  (using  the  WINDOWS.H  identifier) 
SYSTEM _FONT.  The  system  font  is  the  font  that  Windows  uses  for  text  in  caption  bars, 
menus,  and  dialog  boxes. 

Under  Windows  3,  the  system  font  is  a  variable-width  font,  which  means  that  differ¬ 
ent  characters  have  different  widths.  A  “W”  is  wider  than  an  “i.”  In  earlier  versions  of 
Windows,  the  system  font  was  a  fixed-pitch  font  in  which  all  the  characters  had  the  same 
width. 

The  system  font  is  a  “raster  font,”  which  means  that  the  characters  are  defined  as 
blocks  of  pixels.  The  floppy  disks  for  the  Windows  installation  include  several  system 
fonts  in  various  sizes  for  use  with  different  video  display  adapters. 

When  manufacturers  of  a  new  video  board  develop  a  new  Windows  display  driver, 
they  are  also  responsible  for  developing  a  new  system  font  appropriate  for  the  resolution  of 
the  display.  Alternatively,  the  manufacturer  might  specify  that  one  of  the  system  font  files 
supplied  with  the  retail  version  of  Windows  be  used.  The  system  font  must  be  designed  so 
that  at  least  25  lines  of  80-character  text  can  fit  on  the  display.  That  is  the  only  guarantee 
you  have  about  the  relationship  between  screen  size  and  font  size  in  Windows. 
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The  Size  of  a  Character 

To  display  multiple  lines  of  text  using  the  TextOut  function,  you  need  to  determine  the 
dimensions  of  font  characters.  You  can  space  successive  lines  of  text  based  on  the  height  of 
a  character,  and  you  can  space  columns  of  text  across  the  client  area  based  on  the  width 
of  a  character. 

You  can  obtain  character  dimensions  with  the  GetTextMetrics  call.  GetTextMetrics 
requires  a  handle  to  the  device  context  because  it  returns  information  about  the  font  cur¬ 
rently  selected  in  the  device  context.  Windows  copies  the  various  values  of  text  metrics 
into  a  structure  of  type  TEXTMETRIC.  The  values  are  in  units  that  depend  on  the  mapping 
mode  selected  in  the  device  context.  In  the  default  device  context,  this  mapping  mode  is 
MM -TEXT,  so  the  dimensions  are  in  units  of  pixels. 

To  use  the  GetTextMetrics  function,  you  first  need  to  define  a  structure  variable 
(commonly  called  tm)\ 

TEXTMETRIC  tm  ; 

Next,  get  a  handle  to  the  device  context  and  call  GetTextMetrics : 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 

After  you  examine  the  values  in  the  text  metric  structure  (and  probably  save  a  few  of  them 
for  future  use),  you  release  the  device  context: 

ReleaseDC  (hwnd,  hdc)  ; 

Text  Metrics:  The  Details 

The  TEXTMETRIC  structure  provides  a  wealth  of  information  about  the  current  font  se¬ 
lected  in  the  device  context.  However,  the  vertical  size  of  a  font  is  defined  by  only  five 
values,  as  shown  in  Figure  2-3  on  the  following  page. 

These  are  fairly  self-explanatory.  The  tmlnternalLeading  value  is  the  amount  of 
space  allowed  for  an  accent  mark  above  a  character.  If  the  value  is  set  to  0,  accented  capital 
letters  are  made  a  little  shorter  so  that  the  accent  fits  within  the  ascent  of  the  character.  The 
tmExternalLeading  value  is  the  amount  of  space  that  the  designer  of  the  font  suggests  be 
added  between  character  rows.  You  can  accept  or  reject  the  font  designer’s  suggestion  for 
including  external  leading  when  spacing  lines  of  text. 

The  TEXTMETRIC  structure  contains  two  fields  that  describe  character  width: 
tmAveCharWidth  (a  weighted  average  width  of  lowercase  characters)  and  tmMaxChar- 
Width  (the  width  of  the  widest  character  in  the  font).  For  a  fixed-pitch  font,  these  two 
values  are  the  same. 

The  sample  programs  in  this  chapter  will  require  another  character  width — the  av¬ 
erage  width  of  uppercase  letters.  This  can  be  calculated  fairly  accurately  as  150%  of 
tmAveCharWidth . 

t 
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Figure  2-3.  The  five  values  defining  vertical  character  size  in  a  font. 

It’s  important  to  realize  that  the  dimensions  of  the  system  font  are  dependent  on  the 
resolution  of  the  video  display  on  which  Windows  runs.  Windows  provides  a  device¬ 
independent  graphics  interface,  but  you  have  to  help.  Don’t  write  your  Windows  program 
so  that  it  guesses  at  character  dimensions.  Don’t  hard  code  any  values.  Use  the  GetText- 
Metrics  function  to  obtain  this  information. 

Formatting  Text 

Because  the  dimensions  of  the  system  font  do  not  change  during  a  Windows  session,  you 
need  to  call  GetTextMetrics  only  once  when  your  program  executes.  A  good  place  to  make 
this  call  is  while  processing  the  WM -CREATE  message  in  the  window  procedure.  The 
WM -CREATE  message  is  the  first  message  the  window  procedure  receives.  Windows  calls 
your  window  procedure  with  a  WM -CREATE  message  when  you  call  CreateWindow  in 
WinMain . 
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Suppose  you’re  writing  a  Windows  program  that  displays  several  lines  of  text  run¬ 
ning  down  the  client  area.  You’ll  want  to  obtain  values  for  the  character  width  and  height. 
Within  the  window  procedure  you  can  define  two  variables  to  save  the  average  character 
width  ( cxChar )  and  the  total  height  ( cyChary 

static  short  cxChar,  cyChar  ; 

The  prefix  c  added  to  the  variable  names  stands  for  “count,”  and  in  combination  with  x  or 
y  refers  to  a  width  or  a  height.  These  variables  are  defined  as  static  because  they  must  be 
valid  when  the  window  procedure  processes  other  messages  (such  as  WM_PAINT).  If  the 
variables  are  defined  outside  any  functions,  they  need  not  be  defined  as  static. 

Here’s  the  WM_CREATE  code: 

case  WM_CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 

cxChar  =  tm.tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm. tmExternal Leadi ng  ; 

ReleaseDC  (hwnd,  hdc)  ; 
return  0  ; 

If  you  do  not  want  to  include  external  leading  to  space  lines  of  text,  you  can  use: 
cyChar  =  tm.tmHeight  ; 

How  you  use  this  character  size  to  calculate  display  coordinates  is  up  to  you.  A  simple 
method  is  to  leave  a  cyChar  margin  at  the  top  of  the  client  area  and  a  cxChar  margin  at 
the  left.  To  display  several  lines  of  left-justified  text,  use  the  following  x-coordinate  values 
when  calling  the  TextOut  function: 

cxChar 

The  jy -coordinate  values  in  TextOut  are: 
cyChar  *  (1  +  i ) 

where  i  is  the  line  number  starting  at  0. 

You’ll  often  find  it  necessary  to  display  formatted  numbers  as  well  as  simple  charac¬ 
ter  strings.  If  you  were  programming  in  MS-DOS  using  standard  C  library  functions,  you 
would  probably  use  print f  for  this  formatting.  You  cannot  use  print f  in  Windows  because 
print f  writes  to  the  standard  output  device,  and  that  concept  makes  no  sense  under 
Windows. 

Instead,  you  can  use  sprint/ .  The  sprint/  function  works  just  like  print/ except  that 
it  puts  the  formatted  string  into  a  character  array.  You  can  then  use  TextOut  to  write  the 
string  to  the  display.  Very  conveniently,  the  value  returned  from  sprint/  is  the  length  of 
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the  string — you  can  pass  this  value  to  TextOut  as  the  nLength  parameter.  This  code  shows 
a  typical  sprintf  and  TextOut  combination: 

short  nLength  ; 
char  szBuffer  [40]  ; 

[other program  lines] 

nLength  =  sprintf  (szBuffer,  "The  sum  of  %d  and  %d  is  %d", 
nA,  nB,  nA  +  nB)  ; 

TextOut  (hdc,  x,  y,  szBuffer,  nLength)  ; 

For  something  as  simple  as  this  you  could  dispense  with  the  nLength  definition  and 
combine  the  two  statements  into  one: 

TextOut  (hdc,  x,  y,  szBuffer, 

sprintf  (szBuffer,  "The  sum  of  %d  and  %d  is  %d", 
nA,  nB,  nA  +  nB))  ; 

It’s  not  pretty,  but  it  works. 

If  you  don’t  need  to  display  floating-point  numbers,  you  can  use  wsprintf  rather  than 
sprintf.  The  wsprintf  function  has  the  same  syntax  as  sprintf ’  but  it’s  included  in  Windows, 
so  using  it  won’t  increase  the  size  of  your  .EXE  file. 

Putting  It  All  Together 

Now  we  seem  to  have  everything  we  need  to  write  a  simple  program  that  displays  multiple 
lines  of  text  on  the  screen.  We  know  how  to  get  a  handle  to  a  device  context,  how  to  use  the 
TextOut  function,  and  how  to  space  text  based  on  the  size  of  a  single  character.  The  only 
thing  left  to  do  is  to  display  something  interesting. 

The  information  available  in  the  Windows  GetSystemMetrics  call  looks  interesting 
enough.  This  function  returns  information  about  the  size  of  various  graphical  items  in 
Windows,  such  as  icons,  cursors,  caption  bars,  and  scroll  bars.  These  sizes  vary  with  the 
display  adapter  and  driver.  GetSystemMetrics  requires  a  single  parameter  called  an  “in¬ 
dex.”  This  index  is  one  of  forty-two  integer  identifiers  defined  in  WINDOWS.H.  Get¬ 
SystemMetrics  returns  an  integer,  usually  the  size  of  the  item  specified  in  the  parameter. 

Let’s  write  a  program  that  displays  all  the  information  available  from  the  GetSystem¬ 
Metrics  call  in  a  simple  one-line-per-item  format.  Working  with  this  information  is  easier  if 
we  create  a  header  file  that  defines  an  array  of  structures  containing  both  the  WIN¬ 
DOWS.H  identifiers  for  the  GetSystemMetrics  index  and  the  text  we  want  to  display  for 
each  value  returned  from  the  call.  This  header  file  is  called  SYSMETS.H  and  is  shown 
in  Figure  2-4.  If  you  want  to  compile  the  programs  in  this  chapter  for  Windows  3.0  rather 
than  for  Windows  3-1,  remove  the  last  six  elements  of  the  structure  array  shown  in 
SYSMETS.H. 
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SYSMETS.H 


/* . 

SYSMETS.H  --  System  metrics  display  structure 
.  . */ 


//define  NUMLINES 

struct 

{ 

int  nlndex  ; 

((int)  (sizeof  sysmetric 

char  *szLabel  ; 

char  *szDesc  ; 

} 

sysmetrics  []  = 

{ 

SM_CXSCREEN, 

"SM.CXSCREEN", 

SM_CYSCREEN, 

"SM_CYSCREEN", 

SM_CXVSCROLL, 

"SM_CXVSCROLL" , 

SM_CYHSCROLL, 

"SM_CYHSCROLL" , 

SM_CYCAPTION, 

"SM_CYCAPTION" , 

SM.CXBORDER, 

"SM.CXBORDER", 

SM_CYBORDER, 

"SM_CYBORDER", 

SM.CXDLGFRAME, 

"SM_CXDLGFRAME" , 

SM.CYDLGFRAME, 

"SM_CYDLGFRAME", 

SM_CYVTHUMB, 

"SM_CYVTHUMB", 

SM.CXHTHUMB, 

"SM_CXHTHUMB" , 

SM.CXIC0N, 

”SM_CXIC0N", 

SM.CYIC0N, 

"SM_CYIC0N" , 

SM.CXCURSOR, 

"SM_CXCURSOR" , 

SM.CYCURSOR, 

"SM_CYCURSOR" , 

SM.CYMENU, 

"SM_CYMENU", 

SM_CXFULLSCREEN, 

"SM_CXFULLSCREEN" , 

SM_CY FU LLSCREEN , 

"SM_CYFULLSCREEN", 

SM_CYKANJ IWI NDOW , 

"SM_CYKANJ I WINDOW", 

SM_MOUSEPRESENT, 

"SM_MOUSEPRESENT" , 

SM_CYVSCROLL, 

"SM_CYVSCROLL" , 

SM_CXHSCROLL, 

"SM^CXHSCROLL", 

SM.DEBUG, 

"SM_DEBUG", 

SM_SWAPBUTTON, 

"SM_SWAPBUTTON" , 

SM_RESERVED1 , 

"SM_RESERVED1", 

SM_RESERVED2, 

"SM_RESERVED2", 

SM.RESERVED3, 

”SM_RESERVED3", 

SM.RESERVED4, 

"SM_RESERVED4", 

SM_CXMIN, 

"SM_CXMIN" , 

SM_CYMIN, 

"SM_CYMIN" , 

SM.CXSIZE, 

"SM_CXSIZE" , 

SM_CYSIZE, 

"SM_CYSIZE", 

SM_CX FRAME, 

"SM_CX FRAME", 

Figure  2-4.  SYSMETS.H. 


/  sizeof  sysmetrics  [0])) 


"Screen  width  in  pixels", 

"Screen  height  in  pixels", 
"Vertical  scroll  arrow  width", 
"Horizontal  scroll  arrow  height", 
"Caption  bar  height", 

"Window  border  width", 

"Window  border  height", 

"Dialog  window  frame  width", 
"Dialog  window  frame  height", 
"Vertical  scroll  thumb  height", 
"Horizontal  scroll  thumb  width", 
"Icon  width", 

"Icon  height", 

"Cursor  width", 

"Cursor  height", 

"Menu  bar  height", 

"Full  screen  client  area  width", 
"Full  screen  client  area  height", 
"Kanji  window  height", 

"Mouse  present  flag", 

"Vertical  scroll  arrow  height", 
"Horizontal  scroll  arrow  width", 
"Debug  version  flag", 

"Mouse  buttons  swapped  flag", 
"Reserved", 

"Reserved", 

"Reserved", 

"Reserved”, 

"Minimum  window  width", 

"Minimum  window  height", 
"Minimize/Maximize  icon  width", 
"Minimize/Maximize  icon  height", 
"Window  frame  width". 


(continued) 
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SM_CY FRAME, 

SM.CXMINTRACK, 

SM.CYMINTRACK, 

SM_CXDOUBLECLK, 

SM_CYDOUBLECLK, 

SM_CX I  CONS  PAC I NG , 
SM_CY I CONSPAC I NG , 
SM_MENUDROPALIGNMENT, 
SM_PENW I NDOWS , 

}  ; 


MSM_CY FRAME”, 

"SM.CXMINTRACK", 

"SM.CYMINTRACK", 

”SM_CXDOUBLECLK" , 

"SM_CYDOUBLECLK". 

"SM.CXICONSPACING", 

”SM_CYICONSPACING” , 

"SM.MENUDROPALIGNMENT", 

"SM.PENWINDOWS", 


"Window  frame  height", 

"Minimum  window  tracking  width", 
"Minimum  window  tracking  height". 
"Double  click  x  tolerance  (3.1)", 
"Double  click  y  tolerance  (3.1)", 
"Horizontal  icon  spacing  (3.1)", 
"Vertical  icon  spacing  (3.1)", 
"Left  or  right  menu  drop  (3.1)", 
"Pen  extensions  installed  (3.1)" 


The  program  that  displays  this  information  is  called  SYSMETS1.  The  files  required  to 
create  SYSMETS1.EXE  (make  file,  C  source  code,  and  module  definition  file)  are  shown  in 
Figure  2-5.  Most  of  the  code  should  look  familiar  by  now.  With  the  exception  of  the  pro¬ 
gram  name,  the  make  file  and  the  DEF  file  are  almost  identical  to  those  for  HELLOWIN.  In 
SYSMETS1.C,  WinMciin  is  virtually  identical  to  HELLOWIN. 

SYSMETS1  .MAK 

// . . 

//  SYSMETSl .MAK  make  file 
//- . 


sysmetsl.exe  :  sysmetsl.obj  sysmetsl.def 

$(WINLINK)  sysmetsl,  sysmetsl,  NUL,  $(WINLIB),  sysmetsl 
rc  -t  sysmetsl.exe 

sysmetsl.obj  :  sysmetsl. c  sysmets.h 
$ ( WI NCC )  sysmetsl. c 


SYSMETS1.C 


/* - 

SYSMETSl.C 


System  Metrics  Display  Program  No.  1 
(c)  Charles  Petzold,  1992 

*/ 


//include  <wi ndows.fi> 

//include  "sysmets.h" 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


Figure  2-5.  The  SYSMHTS1  program. 


(continued) 
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int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "SysMetsl"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. IpszMenuName 
wndclass. IpszClassName 


CS.HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  IDI.APPLICATION)  ; 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITE_BRUSH)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "Get  System  Metrics  No.  1", 
WS_0V  ERLAPPEDWI NDOW , 

CW_US EDE FAU LT ,  CW.USEDEFAULT, 
CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 
{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  short  cxChar,  cxCaps,  cyChar  ; 


char 
HDC 
short 

PAINTSTRUCT 

TEXTMETRIC 


szBuf f e  r [ 10] 
hdc 
i  ; 
ps  ; 
tm  ; 


(continued) 
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switch  (message) 

{ 

case  WM_CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 
cxChar  =  tm.tmAveCharWidth  ; 

cxCaps  =  (tm.tmPitchAndFamily  &  1  ?  3  :  2)  *  cxChar  /  2  ; 
cyChar  =  tm.tmHeight  +  tm. tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

for  (i  =  0  ;  i  <  NUMLINES  ;  i++) 

{ 

TextOut  (hdc,  cxChar,  cyChar  *  (1  +  i), 
sysmetrics[i].szLabel , 

Istrlen  (sysmetrics[i] .szLabel ) )  ; 

TextOut  (hdc,  cxChar  +  22  *  cxCaps,  cyChar  *  (1  +  i), 
sysmetrics[i].szDesc, 

Istrlen  (sysmetrics[i] .szDesc))  ; 

SetTextAl i gn  (hdc,  TA_RIGHT  !  TA_T0P)  ; 

TextOut  (hdc,  cxChar  +  22  *  cxCaps  +  40  *  cxChar, 
cyChar  *  (1  +  i ) ,  szBuffer, 
wsprintf  (szBuffer,  "%5d", 

GetSystemMetri cs  (sysmetri cs[i  ] . n Index ) ) ) 

SetTextAl ign  (hdc,  TA.LEFT  !  TA_TOP)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQui tMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 
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SYSMETS1.DEF 


SYSMETSl . DEF  module  definition  file 


NAME 


SYSMETSl 


DESCRIPTION  ’System  Metrics  Display  No.  1  (c)  Charles  Petzold,  1992’ 
EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


Figure  2-6  shows  SYSMETSl  running  on  a  VGA.  As  you  can  see  from  the  program’s  win¬ 
dow,  the  screen  width  is  640  pixels  and  the  screen  height  is  480  pixels.  These  two  values, 
as  well  as  many  of  the  other  values  shown  by  the  program,  will  be  different  for  different 
types  of  video  displays. 


1 

f  j  t 

SM  CXSCREEN 

Screen  width  in  pixels 

640 

SM  CYSCREEN 

Screen  height  in  pixels 

480 

SM  CXVSCROLL 

Vertical  scroll  arrow  width 

17 

SM  CYHSCROLL 

Horizontal  scroll  arrow  height 

17 

SM  CYCAPTION 

Caption  bar  height 

20 

SM  CXBORDER 

Border  width 

1 

SM  CYBORDER 

Border  height 

1 

SM  CXDLGFRAME 

Dialog  window  frame  width 

A 

SM  CYDLGFRAME 

Dialog  window  frame  height 

A 

SM  CYVTHUMB 

Vertical  scroll  thumb  height 

17 

SM  CXHTHUMB 

Horizontal  scroll  thumb  width 

17 

SM  CXICON 

Icon  width 

32 

SM  CYICON 

Icon  height 

32 

SM  CXCURSOR 

Cursor  width 

32 

SM  CYCURSOR 

Cursor  height 

32 

SM  CYMENU 

Menu  bar  height 

18 

SM  CXFULLSCREEN 

Full  screen  client  window  width 

640 

SM  CYFULLSCREEN 

Full  screen  client  window  height 

460 

SM  CYKANJIWINDOW 

Kanji  window  height 

0 

SM  MOUSEPRESENT 

Mouse  present  flag 

1 

SM  CYVSCROLL 

Vertical  scroll  arrow  height 

17 

SM  CXHSCROLL 

Horizontal  scroll  arrow  width 

17 

. 

* 

Sir 

'  ■ 

Program 

xT.1’ 

Manager 

_ 

Figure  2-6.  The  SYSMETSl  display. 
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The  SYSMETS1.C  Window  Procedure 

The  WndProc  window  procedure  in  the  SYSMETS1.C  program  processes  three  messages: 
WM -CREATE,  WM_PAINT,  and  WM-DESTROY.  The  WM-DESTROY  message  is  pro¬ 
cessed  in  the  same  way  as  the  HELLOWIN  program  in  Chapter  1. 

The  WM -CREATE  message  is  the  first  message  the  window  procedure  receives.  It  is 
generated  by  Windows  when  the  CreateWindow  function  creates  the  window.  During  the 
WM-CREATE  message,  SYSMETS1  obtains  a  device  context  for  the  window  by  calling 
GetDC  and  gets  the  text  metrics  for  the  default  system  font  by  calling  GetText Metrics. 
SYSMETS1  saves  the  average  character  width  in  cxChar  and  the  total  height  of  the  charac¬ 
ters  (including  external  leading)  in  cyChar. 

SYSMETS1  also  saves  an  average  width  of  uppercase  letters  in  the  static  variable  cx- 
Caps.  For  a  fixed-pitch  font,  cxCaps  would  equal  cxChar.  For  a  variable-width  font,  cxCaps 
is  set  to  150%  of  cxChar.  The  low  bit  of  the  tmPitchAndFamily  field  of  the  TEXTMETRIC 
structure  is  1  for  a  variable-width  font  and  0  for  a  fixed-pitch  font.  SYSMETS1  uses  this  bit 
value  to  calculate  cxCaps  from  cxChar. 

cxCaps  =  (tm. tmPitchAndFamily  &  1  ?  3  :  2)  *  cxChar  /  2  ; 

SYSMETS1  does  all  window  painting  during  the  WM-PAINT  message.  As  normal,  the 
window  procedure  first  obtains  a  handle  to  the  device  context  by  calling  BeginPaint.  A 
for  statement  loops  through  all  the  lines  of  the  sysmetrics  structure  defined  in  SYSMETS.H. 
The  three  columns  of  text  are  displayed  with  three  TextOut  functions.  In  each  case,  the 
third  parameter  to  TextOut  is  set  to: 

cyChar  *  (1  +  i ) 

This  parameter  indicates  the  pixel  position  of  the  top  of  the  character  string  relative 
to  the  top  of  the  client  area.  Thus,  the  program  leaves  a  margin  at  the  top  equal  to  cyChar. 
The  first  line  of  text  (when  i  equals  0)  begins  cyChar  pixels  below  the  top  of  the  client 
area. 

The  first  TextOut  statement  displays  the  uppercase  identifiers  in  the  first  of  the  three 
columns.  The  second  parameter  to  TextOut  is  cxChar.  This  leaves  a  one-character  margin 
between  the  left  edge  of  the  client  area  and  the  text  string.  The  text  is  obtained  from  the 
szLahel  field  of  the  sysmetrics  structure.  I  use  the  Windows  function  Istrlen  (which  is  simi¬ 
lar  to  strlen )  to  obtain  the  length  of  the  string,  which  is  required  as  the  last  parameter 
to  TextOut. 

The  second  TextOut  statement  displays  the  description  of  the  system  metrics  value. 
These  descriptions  are  stored  in  the  szDesc  field  of  the  sysmetrics  structure.  In  this  case, 
the  second  parameter  to  TextOut  is  set  to: 

cxChar  +  22  *  cxCaps 
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The  longest  uppercase  identifier  displayed  in  the  first  column  is  20  characters,  so  the 
second  column  must  begin  at  least  20  x  cxCaps  to  the  right  of  the  beginning  of  the  first 
column  of  text. 

The  third  TextOut  statement  displays  the  numeric  values  obtained  from  the  Get- 
SystemMetrics  function.  The  variable-width  font  makes  formatting  a  column  of  right- 
justified  numbers  a  little  tricky.  All  the  digits  from  0  through  9  have  the  same  width,  but 
this  width  is  greater  than  the  width  of  a  space.  Numbers  can  be  one  or  more  digits  wide,  so 
different  numbers  can  begin  at  different  horizontal  positions. 

Wouldn’t  it  be  easier  if  we  could  display  a  column  of  right-justified  numbers  by 
specifying  the  pixel  position  where  the  number  ends  rather  than  where  it  begins ?  This  is 
what  the  SetTextAlign  function  lets  us  do.  After  SYSMETS1  calls: 

SetTextAl ign  (hdc,  TA_RIGHT  !  TA_T0P)  ; 

the  coordinates  passed  to  subsequent  TextOut  functions  will  specify  the  top-right  corner 
of  the  text  string  rather  than  the  top-left  corner. 

The  TextOut  function  to  display  the  column  of  numbers  has  a  second  parameter 
set  to: 

cxChar  +  22  *  cxCaps  +  40  *  cxChar 

The  40  x  cxChar  value  accommodates  the  width  of  the  second  column  and  the  width  of 
the  third  column.  Following  the  TextOut  function,  another  call  to  SetTextAlign  sets  things 
back  to  normal  for  the  next  time  through  the  loop. 

Not  Enough  Room! 

One  little  nasty  problem  exists  with  the  SYSMETS1  program:  Unless  you  have  a  big-screen, 
high-resolution  video  adapter,  you  can’t  see  the  last  few  lines  of  the  system  metrics  list.  If 
you  make  the  window  narrower,  you  can’t  even  see  the  values. 

SYSMETS1  doesn’t  know  how  large  its  client  area  is.  It  begins  the  text  at  the  top  of  the 
window  and  relies  on  Windows  to  clip  everything  that  drifts  beyond  the  edges  of  the  client 
area.  Our  first  job  is  to  determine  how  much  of  the  program’s  output  can  actually  fit  within 
the  client  area. 

The  Size  of  the  Client  Area 

If  you  experiment  with  existing  Windows  applications,  you’ll  find  that  window  sizes  can 
vary  widely.  At  the  most  (assuming  the  window  does  not  have  a  menu  or  scroll  bars),  the 
window  can  be  maximized,  and  the  client  area  will  occupy  the  entire  screen  except  for  the 
caption  bar.  The  minimum  size  of  the  window  can  be  quite  small,  sometimes  almost  non¬ 
existent,  eliminating  the  client  area. 
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One  common  method  for  determining  the  size  of  a  window’s  client  area  is  to  process 
the  WM_SIZE  message  within  your  window  procedure.  Windows  sends  a  WM_SIZE  mes¬ 
sage  to  a  window  procedure  whenever  the  size  of  the  window  changes.  The  iParam  vari¬ 
able  passed  to  the  window  procedure  contains  the  width  of  the  client  area  in  the  low  word 
and  the  height  in  the  high  word.  The  code  to  process  this  message  often  looks  like  this: 

static  short  cxClient,  cyClient  ; 

[other program  lines] 
case  WM.SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HIWORD  (IParam)  ; 
return  0  ; 

The  LOWORD  and  HIWORD  macros  are  defined  in  WINDOWS.H.  Like  cxChar  and 
cyChar ,  the  cxClient  and  cyClient  variables  are  defined  as  static  inside  the  window  pro¬ 
cedure  because  they  are  used  later  when  processing  other  messages. 

The  WM_SIZE  message  will  eventually  be  followed  by  a  WM_PAINT  message.  Why? 
Because  when  we  define  the  window  class,  we  specify  that  the  class  style  is: 

CS_HREDRAW  !  CS.VREDRAW 

This  class  style  tells  Windows  to  force  a  repaint  if  either  the  horizontal  or  vertical  size 
changes. 

You  can  calculate  the  number  of  full  lines  of  text  displayable  within  the  client  area 
with  the  formula: 

cyClient  /  cyChar 

This  may  be  0  if  the  height  of  the  client  area  is  too  small  to  display  a  full  character.  Simi¬ 
larly,  the  approximate  number  of  lowercase  characters  you  can  display  horizontally  within 
the  client  area  is  equal  to: 

cxClient  /  cxChar 

If  you  determine  cxChar  and  cyChar  during  a  WM -CREATE  message,  don’t  worry  about 
dividing  by  0  in  these  calculations.  Your  window  procedure  receives  a  WM -CREATE  mes¬ 
sage  when  WinMain  calls  CreateWindow.  The  first  WM_SIZE  message  comes  a  little  later 
when  WinMain  calls  ShowWindow ,  at  which  point  cxChar  and  cyChar  have  already  been 
assigned  positive  values. 

Knowing  the  size  of  the  window’s  client  area  is  the  first  step  in  providing  a  way  for 
the  user  to  move  the  text  within  the  client  area  if  the  client  area  is  not  large  enough  to  hold 
everything.  If  you’re  familiar  with  other  Windows  applications  that  have  similar  require¬ 
ments,  you  probably  know  what  we  need:  This  is  a  job  for  scroll  bars. 
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SCROLL  BARS 

Scroll  bars  are  one  of  the  best  features  of  a  graphics  and  mouse  interface.  They  are  easy  to 
use  and  provide  good  visual  feedback.  You  can  use  scroll  bars  whenever  you  need  to  dis¬ 
play  anything — text,  graphics,  a  spreadsheet,  database  records,  pictures — that  requires 
more  space  than  is  available  in  the  client  area  of  the  window. 

Scroll  bars  are  positioned  either  vertically  (for  up  and  down  movement)  or  horizon¬ 
tally  (for  left  and  right  movement).  You  can  click  with  the  mouse  on  the  arrows  at  each  end 
of  a  scroll  bar  or  on  the  area  between  the  arrows.  A  “scroll  box,”  or  “thumb,”  travels  the 
length  of  the  scroll  bar  to  indicate  the  approximate  location  of  the  material  shown  on  the 
display  in  relation  to  the  entire  document.  You  can  also  drag  the  thumb  with  the  mouse  to 
move  to  a  particular  location.  Figure  2-7  shows  the  recommended  use  of  a  vertical  scroll 
bar  for  text. 

Programmers  sometimes  have  problems  with  scrolling  terminology  because  their 
perspective  is  different  from  the  user’s:  A  user  who  scrolls  down  wants  to  bring  a  lower 
part  of  the  document  into  view.  However,  the  program  actually  moves  the  document  up  in 
relation  to  the  display  window.  The  Windows  documentation  and  the  WINDOWS.H  iden¬ 
tifiers  are  based  on  the  user’s  perspective:  Scrolling  up  means  moving  toward  the  begin¬ 
ning  of  the  document;  scrolling  down  means  moving  toward  the  end. 


Click  here  to  scroll 
one  line  up  (contents 
of  window  go  down) 

Click  here  to  scroll 
one  page  or  one 
screenful  up 


Drag  thumb  to  go  to 
approximate  location 


Click  here  to  scroll 
one  page  or  one 
screenful  down 

Click  here  to  scroll 
one  line  down  (contents 
of  window  go  up) 


Figure  2-7.  The  vertical  scroll  bar. 
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It  is  very  easy  to  include  a  horizontal  or  vertical  scroll  bar  in  your  application  window.  All 
you  need  to  do  is  include  the  identifier  WS_VSCROLL  (vertical  scroll)  or  WS_HSCROLL 
(horizontal  scroll)  or  both  in  the  window  style  in  the  CreateWindow  statement.  These 
scroll  bars  are  always  placed  against  the  right  side  or  bottom  of  the  window  and  extend  for 
the  full  length  or  width  of  the  client  area.  The  client  area  does  not  include  the  space  oc¬ 
cupied  by  the  scroll  bar.  The  width  of  a  vertical  window  scroll  bar  and  the  height  of  a  hori¬ 
zontal  window  scroll  bar  are  constant  for  a  particular  display  driver.  If  you  need  these 
values,  you  can  obtain  them  (as  you  may  have  observed)  from  the  GetSystemMetrics  call. 

Windows  takes  care  of  all  mouse  logic  for  the  scroll  bars.  However,  window  scroll 
bars  do  not  have  an  automatic  keyboard  interface.  If  you  want  the  cursor  keys  to  duplicate 
some  of  the  window  scroll  bars’  functions,  you  must  explicitly  provide  logic  for  that  (as 
we’ll  do  in  the  next  chapter). 

Scroll  Bar  Range  and  Position 

Every  scroll  bar  has  an  associated  “range”  (which  is  a  pair  of  integers  representing  a 
minimum  and  maximum  value)  and  a  “position”  (which  is  the  location  of  the  thumb  within 
the  range).  When  the  thumb  is  at  the  top  (or  left)  of  the  scroll  bar,  the  position  of  the  thumb 
is  the  minimum  value  of  the  range.  At  the  bottom  (or  right)  of  the  scroll  bar,  the  thumb  po¬ 
sition  is  the  maximum  value  of  the  range. 

By  default,  the  range  of  a  scroll  bar  is  0  (top  or  left)  through  100  (bottom  or  right),  but 
it’s  easy  to  change  the  range  to  something  that  is  more  convenient  for  the  program: 

SetScrol 1  Range  (hwnd,  nBar,  nMin,  nMax,  bRedraw)  ; 

The  nBar  parameter  is  either  SB_VERT  or  SB-HORZ,  nMin  and  nMax  are  the  minimum 
and  maximum  positions  of  the  range,  and  bRedraw  is  set  to  TRUE  if  you  want  Windows  to 
redraw  the  scroll  bar  based  on  the  new  range. 

The  position  of  the  thumb  is  always  a  discrete  integral  value.  For  instance,  a  scroll  bar 
with  a  range  of  0  through  4  has  five  thumb  positions,  as  shown  in  Figure  2-8.  You  can  use 
SetScrollPos  to  set  a  new  thumb  position  within  the  scroll  bar  range: 

SetScrol 1 Pos  (hwnd,  nBar,  nPos,  nRedraw)  ; 

The  nPos  parameter  is  the  new  position  and  must  be  within  the  range  of  nMin  through 
nMax.  Windows  provides  similar  functions  ( GetScrollRange  and  GetScrollPos)  to  obtain 
the  current  range  and  position  of  a  scroll  bar. 

When  you  use  scroll  bars  within  your  program,  you  share  responsibility  with  Win¬ 
dows  for  maintaining  the  scroll  bars  and  updating  the  position  of  the  scroll  bar  thumb. 
These  are  Windows’  responsibilities  for  scroll  bars: 

■  Handle  all  scroll  bar  mouse  logic. 

■  Provide  a  “reverse  video”  flash  when  the  user  clicks  on  the  scroll  bar. 
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■  Display  a  “ghost”  box  when  the  user  drags  the  thumb  within  the  scroll 
bar. 

■  Send  scroll  bar  messages  to  the  window  procedure  for  the  window  con¬ 
taining  the  scroll  bar. 

These  are  your  program’s  responsibilities: 

■  Initialize  the  range  of  the  scroll  bar. 

■  Process  the  scroll  bar  messages. 

■  Update  the  position  of  the  scroll  bar  thumb. 


Figure  2-8.  Scroll  bars  with  five  thumb  positions. 


Position  0 


Position  1 


Position  2 


Position  3 


Position  4 


Scroll  Bar  Messages 

Windows  sends  the  window  procedure  WM_VSCROLL  and  WM_HSCROLL  messages 
when  the  scroll  bar  is  clicked  with  the  mouse  or  the  thumb  is  dragged.  Each  mouse  action 
on  the  scroll  bar  generates  at  least  two  messages,  one  when  the  mouse  button  is  pressed 
and  another  when  it  is  released. 

The  value  of  wParam  that  accompanies  the  WM_VSCROLL  and  WM_HSCROLL  mes¬ 
sages  is  a  number  that  indicates  what  the  mouse  is  doing  to  the  scroll  bar.  These  values  of 
wParam  have  WINDOWS.H  identifiers  that  begin  with  SB,  which  stands  for  “scroll  bar.” 
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Although  some  of  these  identifiers  use  the  words  “UP”  and  “DOWN,”  they  apply  to  hori¬ 
zontal  as  well  as  vertical  scroll  bars,  as  you  see  in  Figure  2-9.  Your  window  procedure  can 
receive  multiple  SB_LINEUP,  SB_PAGEUP,  SB_LINEDOWN,  or  SB -PAGEDOWN  mes¬ 
sages  if  the  mouse  button  is  held  down  while  positioned  on  the  scroll  bar.  The 
SB-ENDSCROLL  message  signals  that  the  mouse  button  has  been  released.  You  can  gener¬ 
ally  ignore  SB_ENDSCROLL  messages. 


Figure  2-9.  WINDOWS.  H  identifiers  for  the  wParam  values  of  scroll  bar  messages. 

When  wParam  is  SB.THUMBTRACK  or  SB-THUMBPOSITION,  the  low  word  of 
IParam  is  the  current  position  of  the  dragged  scroll  bar.  This  position  is  within  the 
minimum  and  maximum  values  of  the  scroll  bar  range.  For  other  values  of  wParam ,  the 
low  word  of  IParam  should  be  ignored.  You  can  also  ignore  the  high  word  of  IParam. 

The  Windows  documentation  indicates  that  the  wParam  value  can  also  be  SB_TOP 
or  SB_BOTTOM,  indicating  that  the  scroll  bar  has  been  moved  to  its  minimum  or  maxi¬ 
mum  position.  However,  you  will  never  receive  these  values  for  a  scroll  bar  created  as  part 
of  your  application  window. 

Handling  the  SB-THUMBTRACK  and  SB_THUMBPOSITION  messages  is  problem¬ 
atic.  If  you  set  a  large  scroll  bar  range  and  the  user  quickly  drags  the  thumb  inside  the  scroll 
bar,  Windows  sends  your  window  function  a  barrage  of  SB_THUMBTRACK  messages. 
Your  program  may  have  problems  keeping  up  with  these  messages.  For  this  reason,  most 
Windows  applications  ignore  these  messages  and  take  action  only  on  receipt  of 
SB_THUMBPOSITION,  which  means  that  the  thumb  is  again  at  rest. 
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However,  if  you  can  update  your  display  quickly,  you  may  want  to  include 
SB_THUMBTRACK  processing  in  your  program.  But  be  aware  that  users  who  discover  that 
your  program  scrolls  as  they  move  the  scroll  bar  thumb  will  undoubtedly  try  to  move  it  as 
quickly  as  possible  to  see  if  your  program  can  keep  up.  They  will  get  an  inordinate  amount 
of  satisfaction  if  it  cannot. 

Scrolling  SYSMETS 

Enough  explanation.  It’s  time  to  put  this  stuff  into  practice.  But  let’s  start  simply.  We’ll 
begin  with  vertical  scrolling  because  that’s  what  we  desperately  need.  The  horizontal 
scrolling  can  wait.  SYSMETS2  is  shown  in  Figure  2-10. 

The  new  CreateWindow  call  adds  a  vertical  scroll  bar  to  the  window  by  including  the 
WS_VSCROLL  window  style  in  the  CreateWindow  call: 

WS_OVERLAPP EDWIN DOW  !  WS.VSCROLL 

SYSMETS2.MAK 

# 

//  SYSMETS2.MAK  make  file 

# 

sysmets2.exe  :  sysmets2.obj  sysmets2.def 

$(WINLINK)  sysmets2,  sysmets2,  NUL,  $(WINLIB),  sysmets2 
rc  -t  sysmets2.exe 

sysmets2.obj  :  sysmets2.c  sysmets.h 
$(WINCC)  sysmets2.c 


SYSMETS2.C 


/* . - . - . 

SYSMETS2.C  --  System  Metrics  Display  Program  No.  2 
(c)  Charles  Petzold,  1992 

. - . - - - */ 


//include  <windows.h> 

//include  "sysmets.h" 

//define  min(a,b)  .(((a)  <  (b))  ?  (a)  :  (b)) 

//define  max(a,b)  (((a)  >  (b))  ?  (a)  :  (b)) 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


Figure  2-10.  The  SYSMETS2 program. 


(continued) 
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int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "SysMets2"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass. hbrBackground 
wndclass. IpszMenuName 
wndclass. 1 pszCl assName 


CS_HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  IDI.APPLICATION)  ; 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITE_BRUSH)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "Get  System  Metrics  No.  2", 
WS_OVERLAPPEDWI NDOW  !  WS.VSCROLL, 
CW_USEDEFAULT,  COSEDEFAULT, 
COSEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 
{ 

TranslateMessage  (&msg)  ,* 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


{ 


static  short  cxChar,  cxCaps,  cyChar,  cyClient,  nVscrollPos  ; 
char  szBuffer[10]  ; 

HDC  hdc  ; 


short  i ,  y  ; 

PAINTSTRUCT  ps  ; 
TEXTMETRIC  tm  ; 


(continued) 
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switch  (message) 

{ 

case  WM_CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 
cxChar  =  tm.tmAveCharWidth  ; 

cxCaps  =  (tm.tmPitchAndFamily  &  1  ?  3  :  2)  *  cxChar  /  2  ; 
cyChar  =  tm.tmHeight  +  tm. tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 

SetScroll Range  (hwnd,  SBJ/ERT,  0,  NUMLINES,  FALSE)  ; 

SetScrol 1 Pos  (hwnd,  SB_V ERT .  nVscrol 1 Pos .  TRUE)  ; 
return  0  ; 

case  WM.SIZE  : 

cyClient  =  HIWORD  (IParam)  ; 
return  0  ; 

case  WM_VSCROLL  : 
switch  (wParam) 

{ 

case  SB_LI NEUP  : 

nVscrollPos  -=  1  ; 
break  ; 

case  SB_LI N EDOWN  : 

nVscrollPos  +=  1  ; 
break  ; 

case  SB_PAGEUP  : 

nVscrollPos  -=  cyClient  /  cyChar  ; 
break  ; 

case  SB.PAGEDOWN  : 

nVscrollPos  +=  cyClient  /  cyChar  ; 
break  ; 

case  SB_THUMB POS I T I ON  : 

nVscrollPos  =  LOWORD  (IParam)  ; 
break  ; 

default  : 
break  ; 

} 

nVscrollPos  =  max  (0,  min  (nVscrollPos,  NUMLINES))  ; 
if  (nVscrollPos  !=  GetScrollPos  (hwnd,  S B_V ERT)) 

(continued) 
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{ 

SetScrollPos  (hwnd,  SB_VERT,  nVscrollPos,  TRUE)  ; 

Inval idateRect  (hwnd,  NULL.  TRUE)  ; 

} 

return  0  ; 
case  WM__PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

for  (1  =  0  ;  1  <  NUMLINES  ;  i++) 

{ 

y  =  cyChar  *  (1  -  nVscrollPos  +  i)  ; 

TextOut  (hdc,  cxChar,  y, 

sysmetrics[i].szLabel , 

lstrlen  ( sysmet ri cs [i ] .szLabel ) )  : 

TextOut  (hdc,  cxChar  +  22  *  cxCaps,  y, 
sysmetrics[i].szDesc, 
lstrlen  (sysmetrics[i].szDesc))  ; 

SetTextAl ign  (hdc,  TA_RIGHT  J  TA_T0P)  ; 

TextOut  (hdc,  cxChar  +  22  *  cxCaps  +  40  *  cxChar.  y, 
szBuffer, 

wsprintf  (szBuffer,  "%5d", 

GetSystemMetrics  (sysmetrics[i] .nlndex) ) )  ; 

SetTextAl ign  (hdc,  TA_LEFT  !  TA_T0P)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 


return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
} 


SYSMETS2.DEF 


SYSMETS2.DEF  module  definition  file 


(continued) 
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NAME  SYSMETS2 


DESCRIPTION  'System  Metrics  Display  No.  2  (c)  Charles  Petzold,  1992' 
EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


The  WndProc  window  procedure  has  two  additional  lines  to  set  the  range  and  posi¬ 
tion  of  the  vertical  scroll  bar  during  processing  of  the  WM_CREATE  message: 

SetScroll Range  (hwnd,  SB.VERT,  0.  NUMLINES,  FALSE)  ; 

SetScrol 1 Pos  (hwnd,  SB.VERT,  nVscrollPos,  TRUE)  ; 

The  sysmetrics  structure  has  NUMLINES  lines  of  text,  so  the  scroll  bar  range  is  set  from  0 
through  NUMLINES.  Each  position  of  the  scroll  bar  corresponds  to  a  line  of  text  displayed 
at  the  top  of  the  client  area.  If  the  scroll  bar  thumb  is  at  position  0,  a  blank  line  is  left  at  the 
top  of  the  screen  for  a  margin.  As  you  increase  the  position  of  the  scroll  bar  by  scrolling 
down,  the  text  should  move  up.  When  the  scroll  bar  position  is  at  the  bottom,  the  last  line  of 
the  structure  is  at  the  top. 

To  help  with  processing  of  the  WM_VSCROLL  messages,  a  static  variable  called 
nVscrollPos  is  defined  within  the  WndProc  window  procedure.  This  variable  is  the  cur¬ 
rent  position  of  the  scroll  bar  thumb.  For  SB_LINEUP  and  SB_LINEDOWN,  all  we  need 
to  do  is  adjust  the  scroll  position  by  1.  For  SB_PAGEUP  and  SB_PAGEDOWN,  we  want 
to  move  the  text  by  the  contents  of  one  screen,  or  cyClient  divided  by  cyChar. 
For  SB-THUMBPOSITION,  the  new  thumb  position  is  the  low  word  of  iParam. 
SB_ENDSCROLL  and  SB_THUMBTRACK  messages  are  ignored. 

The  nVscrollPos  is  then  adjusted  using  the  min  and  max  macros  to  ensure  that  it  is 
between  the  minimum  and  maximum  range  values.  (These  macros  are  defined  in  WIN- 
DOWS.H,  but  they  are  disabled  when  you  compile  in  C++  mode  with  the  Borland  C++  3.1 
Compiler.  For  this  reason,  definitions  of  min  and  max  are  also  included  near  the  top  of  the 
SYSMETS2.C  source  code.)  If  the  scroll  position  has  changed,  then  it  is  updated  using 
SetScrollPos,  and  the  entire  window  is  invalidated  by  an  InvalidateRect  call. 

The  InvalidateRect  call  generates  a  WM_PAINT  message.  When  the  original 
SYSMETS1  processed  WM -PAINT  messages,  the  j-coordinate  of  each  line  was  calcu¬ 
lated  as: 

cyChar  *  (1  +  i ) 
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In  SYSMETS2,  the  formula  is: 

cyChar  *  (1  -  nVscrollPos  +  i) 

The  loop  still  displays  NUMLINES  lines  of  text,  but  for  values  of  nVscrollPos  of  2  and 
above,  the  loop  begins  displaying  lines  above  the  client  area.  This  is  outside  the  client 
area,  so  Windows  doesn’t  display  those  lines. 

I  told  you  we’d  start  simply.  This  is  rather  wasteful  and  inefficient  code.  We’ll  fix  it 
shortly,  but  first  consider  how  we  update  the  client  area  after  a  WM-VSCROLL  message. 

Structuring  Your  Program  for  Painting 

The  window  procedure  in  SYSMETS2  does  not  repaint  the  client  area  after  processing  a 
scroll  bar  message.  Instead,  it  calls  InvalidateRect  to  invalidate  the  client  area.  This  causes 
Windows  to  place  a  WM_PAINT  message  in  the  message  queue. 

It  is  best  to  structure  your  Windows  programs  so  that  you  do  all  client-area  painting 
in  response  to  a  WM -PAINT  message.  Because  your  program  should  be  able  to  repaint  the 
entire  client  area  of  the  window  at  any  time  on  receipt  of  a  WM_PAINT  message,  you  will 
probably  duplicate  code  if  you  also  paint  in  other  parts  of  the  program. 

At  first,  you  may  rebel  at  this  dictum  because  it  is  so  different  from  normal  PC  pro¬ 
gramming.  I  won’t  deny  that,  on  occasion,  painting  in  response  to  messages  other  than 
WM-PAINT  is  much  more  convenient.  (The  KEYLOOK  program  in  the  next  chapter  is  an 
example  of  such  a  program.)  But  in  many  cases  it’s  simply  unnecessary,  and  after  you  mas¬ 
ter  the  discipline  of  accumulating  all  the  information  you  need  to  paint  in  response  to  a 
WM-PAINT  message,  you’ll  be  pleased  with  the  results.  However,  your  program  will  often 
determine  that  it  must  repaint  a  particular  area  of  the  display  when  processing  a  message 
other  than  WM_PAINT.  This  is  where  InvalidateRect  comes  in  handy.  You  can  use  it  to 
invalidate  specific  rectangles  of  the  client  area  or  the  entire  client  area. 

Simply  marking  areas  of  the  window  as  invalid  to  generate  WM -PAINT  messages 
may  not  be  entirely  satisfactory  in  some  applications.  After  you  make  an  InvalidateRect 
call,  Windows  places  a  WM -PAINT  message  in  the  message  queue,  and  the  window  pro¬ 
cedure  eventually  processes  it.  However,  Windows  treats  WM -PAINT  messages  as  low  pri¬ 
ority.  If  your  message  queue  contains  only  a  WM -PAINT  message  and  another  application 
has  other  messages  waiting,  Windows  switches  to  the  other  application  when  you  make  a 
Get  Message  call. 

If  you  prefer  to  update  the  invalid  area  immediately,  you  can  call  UpdateWindow 
after  you  call  InvalidateRect : 

UpdateWindow  (hwnd)  ; 

UpdateWindow  causes  the  window  procedure  to  be  called  immediately  with  a  WM- 
_PAINT  message  if  any  part  of  the  client  area  is  invalid.  (It  will  not  call  the  window  pro¬ 
cedure  if  the  entire  client  area  is  valid.)  This  WM_PAINT  message  bypasses  the  message 


78 


Chapter  2:  Painting  with  Text 


queue.  The  window  procedure  is  called  directly  from  Windows.  When  the  window  pro¬ 
cedure  has  finished  repainting,  it  exits  and  Windows  returns  control  to  the  program  at  the 
statement  following  the  UpdateWindow  call. 

You’ll  note  that  UpdateWindow  is  the  same  function  used  in  WinMain  to  generate 
the  first  WM-PAINT  message.  When  a  window  is  first  created,  the  entire  client  area  is  in¬ 
valid.  UpdateWindow  directs  the  window  procedure  to  paint  it. 

Building  a  Better  Scroll 

Because  SYSMETS2  is  too  inefficient  a  model  to  be  imitated  in  other  programs,  let’s  clean  it 
up.  SYSMETS3 — our  final  version  of  the  SYSMETS  program  in  this  chapter — is  shown  in 
Figure  2-11.  This  version  adds  a  horizontal  scroll  bar  for  left  and  right  scrolling  and  repaints 
the  client  area  more  efficiently. 

SYSMETS3.MAK 

# 

#  SYSMETS3.MAK  make  file 

# 

sysmets3.exe  :  sysmets3.obj  sysmets3.def 

$(WINL1NK)  sysmets3,  sysmets3,  NUL,  $(WINLIB),  sysmets3 
rc  -t  sysmets3.exe 

sysmets3.obj  :  sysmets3.c  sysmets.h 
MWINCC)  sysmets3.c 


SYSMETS3.C 


/* . 

SYSMETS3 . C  --  System  Metrics  Display  Program  No.  3 
(c)  Charles  Petzold,  1992 


*/ 


^include  <windows.h> 

^include  "sysmets.h" 

#define  min(a,b)  (((a)  <  (b))  ?  (a)  :  (b) ) 

#define  max(a.b)  (((a)  >  (b))  ?  (a)  :  (b) ) 

long  FAR  PASCAL  _export  WndProc  (HWND,  UINT.  UINT,  LONG)  ; 


Figure  2-1 1 .  The  SYSMETS3 program. 


(continued) 
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int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "SysMets3"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS_HREDRAW  !  CS_VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

wndclass. cbWndExtra  =  0  ; 

wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  Loadlcon  (NULL,  IDI_APPLICATION)  ; 

wndclass. hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass. hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
wndclass.lpszMenuName  =  NULL  ; 
wndclass. IpszClassName  =  szAppName  ; 

RegisterClass  (Swndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Get  System  Metrics  No.  3", 

WS_0V E RLAP PEDW I N DOW  !  WS_VSCROLL  i  WS_HSCROLL, 

CW_USEDE FAULT ,  CW_USEDE FAULT , 

CW_USEDEFAULT,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  short  cxChar,  cxCaps,  cyChar,  cxClient,  cyClient,  nMaxWidth, 
nVscrollPos,  nVscrollMax,  nHscrollPos,  nHscrollMax  ; 
char  szBuffer[10]  ; 

HDC  hdc  ; 

short  i,  x,  y,  nPaintBeg,  nPaintEnd,  nVscrol line,  nHscrollInc  ; 

PAINTSTRUCT  ps  ; 

(continued) 
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TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM_CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 
cxChar  =  tm.tmAveCharWidth  ; 

cxCaps  =  (tm.tmPitchAndFamily  &  1  ?  3  :  2)  *  cxChar  /  2  ; 
cyChar  =  tm.tmHeight  +  tm.tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 

nMaxWidth  =  40  *  cxChar  +  22  *  cxCaps  ; 
return  0  ; 

case  WM.SIZE  : 

cxClient  =  LOWORD  ( 1  Pa  ram)  ; 
cyClient  =  HI WORD  (IParam)  ; 

SetScroll Range  (hwnd,  SELVERT,  0,  nVscrollMax,  FALSE)  ; 
SetScrollPos  (hwnd,  SB_VERT,  nVscrollPos,  TRUE)  ; 

nHscrollMax  =  max  (0.  2  +  (nMaxWidth  -  cxClient)  /  cxChar)  ; 
nHscrollPos  =  min  (nHscrol 1 Pos ,  nHscrollMax)  ; 

SetScroll Range  (hwnd,  SB_H0RZ,  0,  nHscrollMax,  FALSE)  ; 
SetScrollPos  (hwnd,  SB_H0RZ,  nHscrollPos,  TRUE)  ; 
return  0  ; 

case  WMJ/SCROLL  : 
switch  (wParam) 

{ 

case  SB_T0P  : 

nVscrol line  =  -nVscrollPos  ; 
break  ; 

case  SB.BOTTOM  : 

nVscrollInc  =  nVscrollMax  -  nVscrollPos  ; 
break  ; 

case  SB_L I N EU P  : 

nVscrollInc  =  -1  ; 
break  ; 

case  SB_LI NEDOWN  : 

nVscrollInc  =  1  ; 
break  ; 


(continued) 
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case  SB.PAGEUP  : 

nVscrolUnc  =  min  (-1,  -cyClient  /  cyChar)  ; 
break  ; 

case  SB.PAGEDOWN  : 

nVscrol line  =  max  (1.  cyClient  /  cyChar)  ; 
break  ; 

case  SB_THUMBTRACK  : 

nVscrolUnc  =  LOWORD  (IParam)  -  nVscrollPos  ; 
break  ; 

default  : 

nVscrolUnc  =  0  ; 

} 

nVscrolUnc  =  max  (-nVscrollPos, 

min  (nVscrolUnc,  nVscrollMax  -  nVscrol  1  Pos) )  ; 

if  (nVscroll Inc  !=  0) 

{ 

nVscrollPos  +=  nVscrolUnc  ; 

ScrollWindow  (hwnd,  0,  -cyChar  *  nVscrolUnc,  NULL,  NULL)  ; 
SetScrollPos  (hwnd,  SB.VERT,  nVscrollPos.  TRUE)  ; 
UpdateWindow  (hwnd)  ; 

} 

return  0  ; 

case  WM_HSCROLL  : 
switch  (wParam) 

{ 

case  SB_LI NEUP  : 

nHscroll Inc  =  -1  ; 
break  ; 

case  SB_LI NEDOWN  : 

nHscroll Inc  =  1  ; 
break  ; 

case  SB.PAGEUP  : 

nHscroll Inc  =  -8  ; 
break  ; 

case  SB.PAGEDOWN  : 

nHscrol 1  Inc  =  8  ; 
break  ; 

case  SB.THUMBPOSITION  : 

nHscrollInc  =  LOWORD  (IParam)  -  nHscrollPos  ; 
break  ; 


(continued) 
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default  : 

nHscrollInc  =  0  ; 

} 

nHscrollInc  =  max  (-nHscrollPos, 

min  (nHscrollInc,  nHscrollMax  -  nHscrollPos))  ; 

if  (nHscrollInc  !=  0) 

{ 

nHscrollPos  +=  nHscrollInc  ; 

ScrollWindow  (hwnd,  -cxChar  *  nHscrollInc,  0.  NULL,  NULL)  ; 
SetScrollPos  (hwnd,  SB_H0RZ.  nHscrollPos,  TRUE)  ; 

} 

return  0  ; 
case  WM_PAINT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

nPaintBeg  =  max  (0,  nVscrollPos  +  ps.rcPaint.top  /  cyChar  -  1)  ; 
nPaintEnd  =  min  (NUMLINES, 

nVscrollPos  +  ps . rcPaint. bottom  /  cyChar)  ; 

for  (i  =  nPaintBeg  ;  i  <  nPaintEnd  ;  i++) 

{ 

x  =  cxChar  *  (1  -  nHscrollPos)  ; 
y  =  cyChar  *  (1  -  nVscrollPos  +  i)  ; 

TextOut  (hdc,  x,  y, 

sysmetrics[i].szLabel , 

lstrlen  ( sysmetri cs[i ] .szLabel ) )  ; 

TextOut  (hdc,  x  +  22  *  cxCaps,  y, 
sysmetrics[i] .szDesc, 
lstrlen  (sysmetrics[i ] .szDesc) )  ; 

SetTextAl ign  (hdc,  TA.RIGHT  !  TA_T0P)  ; 

TextOut  (hdc,  x  +  22  *  cxCaps  +  40  *  cxChar,  y, 
szBuffer , 

wsprintf  (szBuffer,  "%5d'\ 

GetSystemMetrics  (sysmetri cs[i].nlndex)))  ; 

SetTextAl ign  (hdc,  TA_LEFT  !  TA_T0P)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 


(continued) 


83 


SECTION  I:  GETTING  STARTED 


return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


SYSMETS3.DEF 


SYSMETS3.DEF  module  definition  file 


NAME  SYSMETS3 


DESCRIPTION  'System  Metrics  Display  No.  3  (c)  Charles  Petzold,  1992' 
EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


These  are  the  improvements  in  SYSMETS3  and  how  they  are  implemented  in  the  program: 

■  You  can  no  longer  scroll  the  display  so  that  the  last  line  appears  at  the  top 
of  the  client  area.  You  can  scroll  only  far  enough  to  see  the  last  line  at  the 
bottom  of  the  client  area.  This  requires  that  the  program  calculate  a  new 
scroll  bar  range  (and  possibly  a  new  thumb  position)  when  it  processes  a 
WM_SIZE  message.  The  WM_SIZE  logic  calculates  the  scroll  bar  range 
based  on  the  number  of  lines  of  text,  the  width  of  the  text,  and  the  size  of 
the  client  area.  This  approach  results  in  a  smaller  range — only  that 
necessary  to  bring  into  view  the  text  that  falls  outside  the  client  area. 

This  offers  an  interesting  dividend.  Suppose  that  the  client  area  of 
the  window  is  large  enough  to  display  the  entire  text  with  top  and  bottom 
margins.  In  this  case,  both  the  minimum  position  and  maximum  position 
of  the  scroll  bar  range  will  equal  zero.  What  will  Windows  do  with  this 
information?  It  will  remove  the  scroll  bar  from  the  window!  It’s  no  longer 
needed.  Similarly,  if  the  client  area  is  wide  enough  to  show  the  full  60- 
column  width  of  the  text,  no  horizontal  scroll  bar  is  displayed  in  the 
window. 
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■  The  WM_VSCROLL  and  WM_HSCROLL  messages  are  processed  by  first 
calculating  an  increment  of  the  scroll  bar  position  for  each  value  of 
wParam.  This  value  is  then  used  to  scroll  the  existing  contents  of  the 
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window  using  the  Windows  ScrollWindow  call.  This  function  has  the 
following  format: 

ScrollWindow  (hwnd,  xlnc,  ylnc,  IpRect,  lpClipRect)  ; 

The  xlnc  and  ylnc  values  specify  an  amount  to  scroll  in  pixels.  In 
SYSMETS3,  the  IpRect  and  lpClipRect  values  are  set  to  NULL  to  specify 
that  the  entire  client  area  should  be  scrolled.  Windows  invalidates  the 
rectangle  in  the  client  area  “uncovered”  by  the  scrolling  operation.  This 
generates  a  WM_PAINT  message.  InvalidateRect  is  no  longer  needed. 

(Note  that  ScrollWindow  is  not  a  GDI  procedure  because  it  does  not  re¬ 
quire  a  handle  to  a  device  context.  It  is  one  of  the  few  non-GDI  Windows 
functions  that  changes  the  appearance  of  the  client  area  of  a  window.) 

■  The  WM_PAINT  processing  now  determines  which  lines  are  within  the 
invalid  rectangle  and  rewrites  only  those  lines.  It  does  this  by  analyzing 
the  top  and  bottom  coordinates  of  the  invalid  rectangle  stored  in  the 
PAINTSTRUCT  structure.  The  program  paints  only  those  text  lines  within 
the  invalid  rectangle.  The  code  is  more  complex,  but  it  is  much  faster. 

■  Because  WM_PAINT  was  speeded  up,  I  decided  to  let  SYSMETS3  process 
SB  JTHUMBTRACK  operations  for  WM_VSCROLL  messages.  Previously, 
the  program  would  ignore  SB  JTHUMBTRACK  messages  (which  occur 
as  the  user  drags  the  scroll  bar  thumb)  and  would  act  only  on  SB- 
JTHUMBPOSITION  messages,  which  occur  when  the  user  stops  dragging 
the  thumb.  The  WM  JV'SCROLL  code  also  calls  UpdateWindow  to  update 
the  client  area  immediately.  When  you  move  the  thumb  on  the  vertical 
scroll  bar,  SYSMETS3  will  continually  scroll  and  update  the  client  area.  I’ll 
let  you  decide  whether  SYSMETS3  (and  Windows)  is  fast  enough  to  justify 
this  change. 

But  I  Don’t  Like  to  Use  the  Mouse 

If  you  don’t  have  a  mouse  on  your  PC,  you  can’t  scroll  SYSMETS3  at  all.  Scroll  bars  created 
as  part  of  your  application  window  do  not  have  an  automatic  keyboard  interface.  Because 
Windows  can  be  installed  without  a  mouse,  it  is  highly  recommended  that  you  write  pro¬ 
grams  that  do  not  require  the  mouse. 

In  the  next  chapter,  you’ll  learn  how  to  use  the  keyboard  and  how  to  add  a  keyboard 
interface  to  SYSMETS.  You’ll  notice  that  SYSMETS3  seems  to  process  WM-VSCROLL 
messages  where  wParam  equals  SB  JTOP  and  SB_BOTTOM.  I  mentioned  earlier  that  a 
window  procedure  doesn’t  receive  these  messages  for  scroll  bars,  so  right  now  this  is 
superfluous  code.  When  we  come  back  to  this  program  in  the  next  chapter,  you’ll  see  the 
reason  for  including  this  code. 
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Like  most  interactive  programs  that  run  on  personal  computers,  Windows  applications  rely 
heavily  on  the  keyboard  for  user  input.  Although  Windows  also  supports  a  mouse  as  an  in¬ 
put  device,  you  can’t  depend  on  a  mouse  being  present  in  an  installed  version  of  Windows. 
For  this  reason,  program  developers  should  attempt  to  implement  complete  program  func¬ 
tionality  from  the  keyboard.  (Of  course,  in  some  cases,  such  as  drawing  programs  or  desk¬ 
top  publishing  programs,  this  is  simply  not  practical  and  a  mouse  will  be  required.) 

The  keyboard  cannot  be  treated  solely  as  an  input  device  in  isolation  from  other  pro¬ 
gram  functions.  For  example,  programs  often  echo  keyboard  input  by  displaying  typed 
characters  in  the  client  area  of  a  window.  Thus,  handling  keyboard  input  and  displaying 
text  must  be  treated  together.  Sometimes  the  keystrokes  result  in  a  document  being  created 
that  is  eventually  saved  in  a  disk  file,  and  sometimes  a  program  requires  that  the  user  enter 
an  MS-DOS  filename.  These  apparently  straightforward  chores  raise  issues  related  to  the 
support  of  the  ASCII  extended  character  set  (codes  of  128  and  above)  and  of  international 
characters.  For  this  reason,  topics  such  as  the  character  sets  supported  by  Windows  and 
multibyte  character  codes  are  also  covered  in  this  chapter. 


KEYBOARD  BASICS 

As  the  user  presses  and  releases  keys,  the  keyboard  driver  passes  the  keystrokes  to  Win¬ 
dows.  Windows  saves  the  keystrokes  in  the  system  message  queue  and  then  transfers  them 
to  the  message  queue  of  the  program  with  the  “input  focus.”  These  messages  are  processed 
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in  the  program’s  window  procedure.  In  most  cases,  the  keyboard  information  encoded  in 
these  messages  is  probably  more  than  your  program  needs.  Part  of  the  job  of  handling  the 
keyboard  is  knowing  which  messages  are  important  and  which  are  not. 

The  Keyboard  Driver 

Windows  is  shipped  with  several  keyboard  drivers  for  the  support  of  various  keyboard 
hardware  and  international  keyboard  configurations.  Keyboards  for  European  languages 
must  include  additional  characters  (such  as  letters  with  diacritics)  and  symbols  (such  as  the 
British  pound  sign).  When  you  install  Windows,  the  SETUP  program  copies  the  keyboard 
driver  for  the  keyboard  and  country  you  request  into  the  SYSTEM  subdirectory  of  your 
Windows  directory. 

KEYBOARD.DRV  is  a  relatively  small  and  simple  driver.  When  Windows  starts  up,  it 
enables  the  keyboard  driver,  which  responds  by  saving  the  original  interrupt  vector 
addresses  for  Interrupt  09H  (the  hardware  keyboard  interrupt)  and  by  setting  this  interrupt 
vector  to  routines  within  the  driver. 

Pressing  or  releasing  a  key  generates  an  Interrupt  09H.  This  is  sometimes  called  an 
“asynchronous”  interrupt  because  it  can  occur  at  any  time.  The  interrupt  suspends  the 
program  currently  running  and  passes  control  to  the  Interrupt  09H  keyboard  handler. 
When  the  keyboard  handler  is  finished,  it  passes  control  back  to  the  interrupted  program. 
The  Interrupt  09H  keyboard  handler  within  KEYBOARD.DRV  decodes  the  key  and  calls 
a  routine  within  the  Windows  USER  module,  which  stores  them  as  queued  messages. 
The  Windows  program  then  obtains  the  keyboard  messages  when  the  program  calls 
GetMessage. 

Because  a  Windows  program  effectively  polls  for  keyboard  input  by  calling  Get- 
Message ;  Windows  programs  are  not  very  different  from  PC  programs  that  obtain  key¬ 
strokes  by  polling  through  the  software  Interrupts  16H  and  21H.  However,  the  quantity  of 
information  that  Windows  encodes  in  the  keyboard  messages  is  much  greater  than  that 
available  from  the  PC  BIOS  or  MS-DOS. 

Some  application  programs  written  for  the  IBM  PC  intercept  Interrupt  09H  and  do 
their  own  hardware  keyboard  processing.  This  allows  the  program  to  use  all  possible  com¬ 
binations  of  keystrokes,  not  only  those  defined  by  the  PC  BIOS.  Windows  programs  are  not 
very  different  from  these  programs  either,  because  the  window  procedure  is  a  message 
handler  that  receives  messages  about  all  keyboard  events.  The  only  real  difference  be¬ 
tween  message  handling  and  interrupt  handling  is  that  the  Windows  messages  are  not 
asynchronous.  A  Windows  program  is  never  interrupted  to  be  notified  of  a  keystroke;  the 
program  receives  a  new  keyboard  message  only  from  the  message  queue.  In  short,  Win¬ 
dows  provides  programs  with  all  the  benefits  of  intercepting  the  hardware  Interrupt  09H 
but  with  none  of  the  hassles. 

When  a  user  types  on  the  keyboard  faster  than  a  program  can  process  the  keys,  Win¬ 
dows  stores  the  extra  keystrokes  in  a  system  message  queue  rather  than  in  an  individual 
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program’s  message  queue.  One  of  these  extra  keystrokes  (Alt-Tab,  for  instance)  may  have 
the  effect  of  switching  input  focus  to  another  program.  The  keys  following  Alt-Tab  should 
then  go  to  the  other  program.  Windows  correctly  synchronizes  such  keyboard  messages. 

Windows  sends  eight  different  messages  to  programs  to  indicate  various  keyboard 
events.  That  may  seem  like  a  lot,  but  your  program  can  safely  ignore  many  of  them. 

Ignoring  the  Keyboard 

Although  the  keyboard  is  the  primary  source  of  user  input  to  Windows  programs,  your 
program  does  not  need  to  act  on  every  keyboard  message  it  receives.  Windows  handles 
many  keyboard  functions  itself.  For  instance,  you  can  ignore  keystrokes  that  pertain  to 
system  functions.  These  keystrokes  generally  involve  the  Alt  key. 

A  program  need  not  monitor  these  keystrokes  because  Windows  notifies  a  program 
of  the  effect  of  the  keystrokes.  (A  program  can  monitor  the  keystrokes  if  it  wants  to,  how¬ 
ever.)  For  instance,  if  the  Windows  user  selects  a  menu  item  with  the  keyboard,  Win¬ 
dows  sends  the  program  a  message  that  the  menu  item  has  been  selected,  regardless  of 
whether  it  was  selected  by  using  the  mouse  or  by  using  the  keyboard.  (Menus  are  covered 
in  Chapter  9.) 

Some  Windows  programs  use  “keyboard  accelerators”  to  invoke  common  menu 
items.  The  accelerators  generally  involve  the  function  keys,  special  noncharacter  keys 
such  as  Insert  or  Delete,  or  a  letter  in  combination  with  the  Ctrl  key.  These  keyboard  ac¬ 
celerators  are  defined  in  a  program’s  resource  script.  (Chapter  9  shows  how  Windows 
translates  the  accelerators  into  menu  command  messages.  You  don’t  have  to  do  the  trans¬ 
lation  yourself.) 

Dialog  boxes  (covered  in  Chapter  10)  also  have  a  keyboard  interface,  but  programs 
usually  do  not  need  to  monitor  the  keyboard  when  a  dialog  box  is  active.  The  keyboard 
interface  is  handled  by  Windows,  and  Windows  sends  messages  to  your  program  about  the 
effects  of  the  keystrokes.  Dialog  boxes  can  contain  “edit”  controls  for  text  input.  These  are 
generally  small  boxes  in  which  the  user  types  a  character  string.  Windows  handles  all  the 
edit  control  logic  and  gives  your  program  the  final  contents  of  the  edit  control  when 
the  user  is  done. 

Even  within  your  main  window  you  can  define  child  windows  that  function  as  edit 
controls.  An  extreme  example  of  this  is  the  Windows  NOTEPAD  program,  which  is  little 
more  than  a  large  multiline  edit  control.  NOTEPAD  does  little  keyboard  processing  on 
its  own  and  relies  on  Windows  to  handle  all  the  dirty  work.  (Chapter  6  discusses  how 
this  works.) 

Focus,  Focus,  Who’s  Got  the  Focus? 

The  keyboard  must  be  shared  by  all  applications  running  under  Windows.  Some  applica¬ 
tions  may  have  more  than  one  window,  and  the  keyboard  must  be  shared  by  these  win¬ 
dows  within  the  same  application.  When  a  key  on  the  keyboard  is  pressed,  only  one 
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window  procedure  can  receive  a  message  that  the  key  has  been  pressed.  The  window  that 
receives  this  keyboard  message  is  the  window  with  the  “input  focus.” 

The  concept  of  input  focus  is  closely  related  to  the  concept  of  “active  window.”  The 
window  with  the  input  focus  is  either  the  active  window  or  a  child  window  of  the  active 
window.  The  active  window  is  usually  easy  to  identify.  If  the  active  window  has  a  caption 
bar,  Windows  highlights  the  caption  bar.  If  the  active  window  has  a  dialog  frame  (a  form 
most  commonly  seen  in  dialog  boxes)  instead  of  a  caption  bar,  Windows  highlights  the 
frame.  If  the  active  window  is  an  icon,  Windows  highlights  the  window’s  caption  bar  text 
below  the  icon. 

The  most  common  child  windows  are  controls  such  as  push  buttons,  radio  buttons, 
check  boxes,  scroll  bars,  edit  boxes,  and  list  boxes  that  usually  appear  in  a  dialog  box. 
Child  windows  are  never  themselves  active  windows.  If  a  child  window  has  the  input 
focus,  then  the  active  window  is  its  parent.  Child  window  controls  indicate  that  they  have 
the  input  focus  generally  by  using  a  flashing  cursor  or  caret. 

If  the  active  window  is  an  icon,  then  no  window  has  the  input  focus.  Windows  con¬ 
tinues  to  send  keyboard  messages  to  the  icon,  but  these  messages  are  in  a  different  form 
from  keyboard  messages  sent  to  active  windows  that  are  not  icons. 

A  window  procedure  can  determine  when  it  has  the  input  focus  by  trapping 
WM _SETFOCUS  and  WM_KILLFOCUS  messages.  WM_SETFOCUS  indicates  that  the  win¬ 
dow  is  receiving  the  input  focus,  and  WM_KILLFOCUS  signals  that  the  window  is  losing 
the  input  focus. 

Keystrokes  and  Characters 

The  messages  that  an  application  receives  from  Windows  about  keyboard  events  distin¬ 
guish  between  “keystrokes”  and  “characters.”  This  is  in  accordance  with  the  two  ways  you 
can  view  the  keyboard.  First,  you  can  think  of  the  keyboard  as  a  collection  of  keys.  The 
keyboard  has  only  one  A  key.  Pressing  that  key  is  a  keystroke.  Releasing  that  key  is  a  key¬ 
stroke.  But  the  keyboard  is  also  an  input  device  that  generates  displayable  characters.  The 
A  key  can  generate  several  characters  depending  on  the  status  of  the  Ctrl,  Shift,  and  Caps 
Lock  keys.  Normally,  the  character  is  a  lowercase  a.  If  the  Shift  key  is  down  or  Caps  Lock  is 
toggled  on,  the  character  is  an  uppercase  A.  If  Ctrl  is  down,  the  character  is  a  Ctrl-A.  On  a 
foreign-language  keyboard,  the  A  keystroke  may  be  preceded  by  a  “dead-character  key”  or 
by  Shift,  Ctrl,  or  Alt  in  various  combinations.  The  combinations  could  generate  a  lowercase 
a  or  an  uppercase  A  with  an  accent  mark. 

For  keystroke  combinations  that  result  in  displayable  characters,  Windows  sends  a 
program  both  keystroke  messages  and  character  messages.  Some  keys  do  not  generate 
characters.  These  include  the  shift  keys,  the  function  keys,  the  cursor  movement  keys,  and 
special  keys  such  as  Insert  and  Delete.  For  these  keys,  Windows  generates  only  keystroke 
messages. 
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KEYSTROKE  MESSAGES 


When  you  press  a  key,  Windows  places  either  a  WM-KEYDOWN  or  WM _SYSKE YDOWN 
message  in  the  message  queue  of  the  window  with  the  input  focus.  When  you  release  a  key, 
Windows  places  either  a  WM_KEYUP  or  WM-SYSKEYUP  message  in  the  message  queue. 


Key  Pressed 

Key  Released 

Nonsystem  Keystroke: 

WM_KEYDOWN 

WM-KEYUP 

System  Keystroke: 

WM_SYSKEYDOWN 

WM_SYSKEYUP 

Usually  the  “down”  and  “up”  messages  occur  in  pairs.  However,  if  you  hold  down 
a  key  so  that  the  typematic  (autorepeat)  action  takes  over,  Windows  sends  the  window 
procedure  a  series  of  WM_KEYDOWN  (or  WM-SYSKEYDOWN)  messages  and  a  single 
WM-KEYUP  (or  WM_SYSKEYUP)  message  when  the  key  is  finally  released.  Like  all 
queued  messages,  keystroke  messages  are  time-stamped.  You  can  obtain  the  relative  time  a 
key  was  pressed  or  released  by  calling  GetMessageTime. 

System  and  Nonsystem  Keystrokes 

The  “SYS”  in  WM_SYSKE YDOWN  and  WM_SYSKEYUP  stands  for  “system”  and  refers  to 
keystrokes  that  are  more  important  to  Windows  than  to  the  Windows  application.  The 
WM_SYSKE YDOWN  and  WM_SYSKEYUP  messages  are  usually  generated  for  keys  typed 
in  combination  with  the  Alt  key.  These  keystrokes  invoke  options  on  the  program’s  menu 
or  system  menu,  or  they  are  used  for  system  functions  such  as  switching  the  active  window 
(Alt-Tab  or  Alt-Esc)  or  for  system  menu  accelerators  (Alt  in  combination  with  a  function 
key).  Programs  usually  ignore  the  WM_SYSKEYUP  and  WM_SYSKE YDOWN  messages 
and  pass  them  to  DefWindowProc.  Because  Windows  takes  care  of  all  the  Alt-key  logic, 
you  really  have  no  need  to  trap  these  messages.  Your  window  procedure  will  eventually 
receive  other  messages  concerning  the  result  of  these  keystrokes  (such  as  a  menu  selec¬ 
tion).  If  you  want  to  include  code  in  your  window  procedure  to  trap  the  system  keystroke 
messages  (as  we  will  do  in  the  KEYLOOK  program  later  in  this  chapter),  pass  the  messages 
to  DefWindowProc  after  you  process  them  so  that  Windows  can  still  use  them  for  their 
normal  purposes. 

But  think  about  this  for  a  moment.  Almost  everything  that  affects  your  program’s 
window  passes  through  your  window  procedure  first.  Windows  does  something  with  the 
message  only  if  you  pass  the  message  to  DefWindowProc.  For  instance,  if  you  add  the  lines: 

case  WM_SYSKEYDOWN  : 
case  WM.SYSKEYUP  : 
case  WM_SYSCHAR  : 
return  0  ; 

to  a  window  procedure,  then  you  effectively  disable  all  Alt-key  operations  (menu  com¬ 
mands,  Alt-Tab,  Alt-Esc,  and  so  on)  when  your  program  has  the  input  focus.  Although  I 
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doubt  you  would  want  to  do  this,  I  trust  you’re  beginning  to  sense  the  power  in  your 
window  procedure. 

The  WM_KEYDOWN  and  WM_KEYUP  messages  are  usually  generated  for  keys  that 
are  pressed  and  released  without  the  Alt  key.  Your  program  may  use  or  discard  these  key¬ 
stroke  messages.  Windows  itself  doesn’t  care  about  them. 

The  IParam  Variable 

For  all  four  keystroke  messages,  the  32-bit  IParam  variable  passed  to  the  window 
procedure  is  divided  into  six  fields:  Repeat  Count,  OEM  Scan  Code,  Extended  Key  Flag, 
Context  Code,  Previous  Key  State,  and  Transition  State.  (See  Figure  3-1.) 

Extended  Key  Flag 


31 

30 

29 

28 

27 

26 

25 

24 

23 

16 

15 

00 

_ 1 _ 1 

L  Context  Code  8-bit  OEM  ItJblt 

L  Previous  Key  State  Scan  Code  Repeat  Count 
*—  Transition  State 


Figure  3-1 .  The  six  keystroke -message  fields  of  the  IParam  variable. 

Repeat  Count 

The  Repeat  Count  is  the  number  of  keystrokes  represented  by  the  message.  In  most  cases 
the  Repeat  Count  is  set  to  1.  However,  if  a  key  is  held  down  and  your  window  procedure 
is  not  fast  enough  to  process  key-down  messages  at  the  typematic  rate  (approximately 
a  10-character-per-second  default),  Windows  combines  several  WM-KEYDOWN  or 
WM_SYSKEYDOWN  messages  into  a  single  message  and  increases  Repeat  Count  accord¬ 
ingly.  The  Repeat  Count  is  always  1  for  a  WM_KEYUP  or  WM_SYSKEYUP  message. 

Because  a  Repeat  Count  greater  than  1  indicates  that  typematic  keystrokes  are  occur¬ 
ring  faster  than  your  program  can  process  them,  you  may  want  to  ignore  the  Repeat  Count 
when  processing  the  keyboard  messages.  Almost  everyone  has  had  the  experience  of 
“overscrolling”  a  word-processing  document  or  spreadsheet  because  extra  keystrokes 
have  stacked  up  in  the  keyboard  buffer.  Ignoring  the  Repeat  Count  in  your  program  will 
significantly  reduce  the  possibilities  for  overscrolling.  However,  in  other  cases  you  will 
want  to  use  the  Repeat  Count.  You  should  probably  try  your  programs  both  ways  and  see 
which  approach  feels  the  most  natural. 

OEM  Scan  Code 

The  OEM  Scan  Code  is  the  keyboard  scan  code  generated  by  the  hardware  of  the  com¬ 
puter.  For  the  IBM  PC,  this  scan  code  is  the  same  as  the  value  passed  back  to  a  program  in 
register  AH  during  a  BIOS  Interrupt  16H  call.  Windows  applications  generally  ignore  the 
OEM  Scan  Code  because  there  are  better  ways  to  decode  keyboard  information. 
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Extended  Key  Flag 

The  Extended  Key  Flag  is  1  if  the  keystroke  results  from  one  of  the  additional  keys  on  the 
IBM  Enhanced  Keyboard.  (The  IBM  Enhanced  Keyboard  has  function  keys  across  the  top 
and  a  separate  [combined]  keypad  for  cursor  keys  and  number  keys.)  This  flag  is  set  to  1  for 
the  Alt  and  Ctrl  keys  at  the  right  of  the  keyboard,  the  cursor  movement  keys  (including 
Insert  and  Delete)  that  are  not  part  of  the  numeric  keypad,  the  Slash  (/)  and  Enter  keys  on 
the  numeric  keypad,  and  the  Num  Lock  key.  Windows  programs  generally  ignore  the 
Extended  Key  Flag. 

Context  Code 

The  Context  Code  is  1  if  the  Alt  key  is  pressed.  This  bit  will  always  be  1  for  the 
WM_SYSKEYUP  and  WM  _S Y SKE YDOWN  messages  and  0  for  the  WM.KEYUP  and 
WM_KE  YDOWN  messages,  with  two  exceptions: 

■  If  the  active  window  is  an  icon,  it  does  not  have  the  input  focus.  All 
keystrokes  generate  WM_SYSKEYUP  and  WM.SYSKE  YDOWN  mes¬ 
sages.  If  the  Alt  key  is  not  pressed,  the  Context  Code  field  is  set  to  0. 
(Windows  uses  SYS  keyboard  messages  so  that  the  active  window  that  is 
an  icon  doesn’t  process  these  keystrokes.) 

■  On  some  foreign-language  keyboards,  certain  characters  are  generated 
by  combining  Shift,  Ctrl,  or  Alt  with  another  key.  In  these  cases  the 
IParam  variable  that  accompanies  WM_KEYUP  and  WM_KEYDOWN 
messages  has  a  1  in  the  Context  Code  field,  but  the  messages  are  not 
system  keystroke  messages. 

Previous  Key  State 

The  Previous  Key  State  is  0  if  the  key  was  previously  up  and  1  if  the  key  was  previously 
down.  It  is  always  set  to  1  for  a  WM_KEYUP  or  WM_SYSKEYUP  message,  but  it  can  be  0  or 
1  for  a  WM_KEYDOWN  or  WM_SYSKEYDOWN  message.  A  1  indicates  second  and  subse¬ 
quent  messages  for  keys  that  are  the  result  of  typematic  action. 

Transition  State 

The  Transition  State  is  0  if  the  key  is  being  pressed  and  1  if  the  key  is  being  released.  The 
field  is  set  to  0  for  a  WM_KE YDOWN  or  WM_SYSKE YDOWN  message  and  to  1  for  a 
WM_KEYUP  or  WM_SYSKEYUP. 

Virtual  Key  Codes 

Although  some  information  in  IParam  might  be  useful  for  processing  WM_KEYUP, 
WM.KEYDOWN,  WM_SYSKEYUP,  and  WM_SYSKE YDOWN  messages,  the  wParam  pa¬ 
rameter  is  much  more  important.  This  parameter  contains  the  “virtual  key  code”  that  iden¬ 
tifies  the  key  that  was  pressed  or  released.  The  developers  of  Windows  have  attempted 
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_ VIRTUAL  KEY  CODES _ 

WINDOWS.  H 

Decimal  Hex  Identifier  Required  IBM  Keyboard 


1 

01 

VK-LBUTTON 

2 

02 

VK-RBUTTON 

3 

03 

VK-CANCEL 

4 

04 

VK-MBUTTON 

8 

08 

VK-BACK 

9 

09 

VK_TAB 

12 

OC 

VK-CLEAR 

13 

0D 

VK-RETURN 

16 

10 

VK-SHIFT 

17 

11 

VK -CONTROL 

18 

12 

VK-MENU 

19 

13 

VK-PAUSE 

20 

14 

VK-CAPITAL 

27 

IB 

VK-ESCAPE 

32 

20 

VK -SPACE 

33 

21 

VK-PRIOR 

34 

22 

VK-NEXT 

35 

23 

VK-END 

36 

24 

VK-HOME 

37 

25 

VK-LEFT 

38 

26 

VK_UP 

39 

27 

VK-RIGHT 

40 

28 

VK-DOWN 

41 

29 

VK-SELECT 

42 

2A 

VK-PRINT 

43 

2B 

VK-EXECUTE 

44 

2C 

VK-SNAPSHOT 

45 

2D 

VK-INSERT 

46 

2E 

VK-DELETE 

47 

2F 

VK-HELP 

48-57 

30-39 

65-90 

41-5A 

96 

60 

VK-NUMPAD0 

Ctrl-Break 

Backspace 

Tab 

Numeric  keypad  5  with  Num  Lock  OFF 

Enter 

Shift 

Ctrl 

Alt 

Pause 

Caps  Lock 

Esc 

Spacebar 
Page  Up 
Page  Down 
End 
Home 
Left  Arrow 
Up  Arrow 
Right  Arrow 
Down  Arrow 


Print  Screen 

Insert 

Delete 

0  through  9  on  main  keyboard 
A  through  Z 

Numeric  keypad  0  with  Num  Lock  ON 


(continued) 
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VIRTUAL  KEY  CODES  continued 

WINDOWS.  H 

Decimal  Hex  Identifier  Required  IBM  Keyboard 


97 

61 

VK-NUMPAD1 

98 

62 

VK-NUMPAD2 

99 

63 

VK-NUMPAD3 

100 

64 

VK-NUMPAD4 

101 

65 

VK-NUMPAD5 

102 

66 

VK-NUMPAD6 

103 

67 

VK-NUMPAD7 

104 

68 

VK-NUMPAD8 

103 

69 

VK-NUMPAD9 

106 

6A 

VK-MULTIPLY 

107 

6B 

VK-ADD 

108 

6C 

VK-SEPARATOR 

109 

6D 

VK-SUBTRACT 

110 

6E 

VK-DECIMAL 

111 

6F 

VK-DIVIDE 

112 

70 

VK_F1 

113 

71 

VK_F2 

114 

72 

VK_F3 

113 

73 

VK_F4 

116 

74 

VK_F5 

117 

75 

VK_F6 

118 

76 

VK-F7 

119 

77 

VK_F8 

120 

78 

VK_F9 

121 

79 

VK-F10 

122 

7A 

VK-Fll 

123 

7B 

VK-F12 

124 

7C 

VK-F13 

Numeric  keypad  1  with  Num  Lock  ON 
Numeric  keypad  2  with  Num  Lock  ON 
Numeric  keypad  3  with  Num  Lock  ON 
Numeric  keypad  4  with  Num  Lock  ON 
Numeric  keypad  5  with  Num  Lock  ON 
Numeric  keypad  6  with  Num  Lock  ON 
Numeric  keypad  7  with  Num  Lock  ON 
Numeric  keypad  8  with  Num  Lock  ON 
Numeric  keypad  9  with  Num  Lock  ON 

Numeric  keypad  *  (enhanced 
keyboard) 

Numeric  keypad  +  (enhanced 
keyboard) 

Numeric  keypad  -  (enhanced 
keyboard) 

Numeric  keypad 

Numeric  keypad  /(enhanced 
keyboard) 

Function  key  FI 
Function  key  F2 
Function  key  F3 
Function  key  F4 
Function  key  F5 
Function  key  F6 
Function  key  F7 
Function  key  F8 
Function  key  F9 
Function  key  F10 
Function  key  Fll  (enhanced 
keyboard) 

Function  key  FI 2  (enhanced 
keyboard) 


(continued) 
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VIRTUAL  KEY  CODES  continued 


Decimal 

Hex 

WINDOWS.H 

Identifier 

Required  IBM  Keyboard 

125 

7D 

VK-F14 

126 

7E 

VK-F15 

127 

7F 

VK-F16 

144 

90 

VK-NUMLOCK 

Num  Lock 

145 

91 

VK-SCROLL 

Scroll  Lock 

to  define  virtual  keys  in  a  device-independent  manner.  For  this  reason,  some  virtual  key 
codes  cannot  be  generated  on  the  IBM  PC  and  strict  compatibles  but  may  be  found  on 
other  manufacturer’s  keyboards. 

The  virtual  key  codes  you  use  most  often  have  names  defined  in  WINDOWS.H.  The 
table  above  shows  these  names  along  with  the  numeric  key  codes  and  the  IBM  PC  key  that 
corresponds  to  the  virtual  key.  Although  all  keys  cause  keystroke  messages,  the  table  does 
not  include  any  symbol  keys  (such  as  the  key  with  the  /  and  ?  symbols).  These  keys  have 
virtual  key  codes  of  128  and  above,  and  they  are  often  defined  differently  for  international 
keyboards.  You  can  determine  the  values  of  these  virtual  key  codes  using  the  KEYLOOK 
program  that  is  shown  later  in  this  chapter,  but  normally  you  should  not  process  keystroke 
messages  for  these  keys. 

An  asterisk  (*)  in  the  column  labeled  “Required”  indicates  that  the  key  is  mandatory 
for  any  Windows  implementation.  Windows  also  requires  that  a  keyboard  and  keyboard 
driver  allow  the  Shift,  Ctrl,  and  Shift  and  Ctrl  keys  together  to  be  combined  with  all  letter 
keys,  all  required  cursor  keys,  and  all  required  function  keys.  The  VK_LBUTTON, 
VK_MBUTTON,  and  VK_RBUTTON  virtual  key  codes  refer  to  the  left,  middle,  and  right 
buttons  of  a  mouse.  However,  you  will  never  receive  keystroke  messages  with  wParam  set 
to  these  values.  The  mouse  generates  its  own  messages. 

Shift  States 

The  wParam  and  IParam  parameters  that  accompany  WM_KEYDOWN,  WM-KEYUP, 
WM_SYSKEYDOWN,  and  WM.SYSKEYUP  messages  do  not  tell  your  program  about  the 
state  of  the  shift  keys.  You  can  obtain  the  current  state  of  any  virtual  key  using  the  GetKey- 
State  function.  This  function  generally  is  used  to  obtain  the  state  of  shift  keys  (Shift,  Ctrl, 
and  Alt)  and  toggle  keys  (Caps  Lock,  Num  Lock,  and  Scroll  Lock).  For  instance: 

GetKeyState  (VK_SHIFT)  ; 

returns  a  negative  value  (that  is,  the  high  bit  is  set)  if  the  Shift  key  is  down.  The  value 
returned  from: 

GetKeyState  (VK_CAPITAL)  ; 


98 


Chapter  3:  The  Keyboard 


has  the  low  bit  set  if  the  Caps  Lock  key  is  toggled  on.  You  can  also  obtain  the  state  of 
the  mouse  buttons  using  the  virtual  key  codes  VK_LBUTTON,  VK_RBUTTON,  and 
VK_MBUTTON.  However,  most  Windows  programs  that  need  to  monitor  a  combination  of 
mouse  buttons  and  keystrokes  usually  do  it  the  other  way  around — by  checking  key¬ 
strokes  when  they  receive  a  mouse  message.  In  fact,  shift-state  information  is  included  in 
the  mouse  messages  (as  you’ll  see  in  the  next  chapter). 

Be  careful  with  GetKeyState.  It  is  not  a  real-time  keyboard  status  check.  Rather,  it  is  a 
check  of  the  keyboard  status  up  to  and  including  the  current  message  being  processed. 
GetKeyState  does  not  let  you  retrieve  keyboard  information  independent  of  normal 
keyboard  messages.  For  instance,  you  may  want  to  hold  up  processing  in  your  window 
procedure  until  the  user  presses  the  FI  function  key: 

while  (GetKeyState  (VK_F1)  >=  0)  ;  //  WRONG  !!! 

This  statement  will  execute  for  a  very  long  time — until  you  reset  your  machine  with  Ctrl- 
Alt-Delete.  Your  program  must  retrieve  the  keyboard  message  from  the  queue  before 
GetKeyState  can  retrieve  the  state  of  the  key.  This  synchronization  actually  works  to  your 
advantage  because  if  you  need  to  know  the  shift  state  for  a  particular  keystroke  message, 
GetKeyState  is  guaranteed  to  be  accurate,  even  if  you  are  processing  the  message  after  the 
shift  key  has  been  released.  If  you  really  need  the  current  state  of  the  key,  you  can  use 
Get AsyncKey State. 

Using  Keystroke  Messages 

The  idea  of  a  program  getting  information  about  every  keystroke  is  certainly  nice,  but  most 
Windows  programs  ignore  all  but  a  few  keystroke  messages.  The  WM-SYSKEYDOWN  and 
WM-SYSKEYUP  messages  are  for  Windows  system  functions,  and  you  don’t  need  to  look 
at  them.  If  you  process  WM_KEYDOWN  messages,  you  can  also  ignore  WM_KEYUP 
messages. 

Windows  programs  generally  use  WM_KEYDOWN  messages  for  keystrokes  that  do 
not  generate  characters.  Although  you  may  think  that  it’s  possible  to  use  keystroke  mes¬ 
sages  in  combination  with  shift-state  information  to  translate  keystroke  messages  into 
character  messages,  don’t  do  it.  You’ll  have  problems  with  international  keyboard  differ¬ 
ences.  For  instance,  if  you  get  a  WM_KEYDOWN  message  with  wParam  equal  to  33H,  you 
know  the  user  pressed  the  3  key.  So  far,  so  good.  If  you  use  GetKeyState  and  find  out  that 
the  Shift  key  is  down,  you  might  assume  that  the  user  is  typing  a  pound  sign  (#).  Not  neces¬ 
sarily  so.  A  British  user  is  typing  a  £.  So  the  WM-KEYDOWN  messages  are  most  useful  for 
the  cursor  movement  keys,  the  function  keys,  and  special  keys  such  as  Insert  and  Delete. 
However,  Insert,  Delete,  and  the  function  keys  often  appear  as  menu  accelerators.  Because 
Windows  translates  menu  accelerators  into  menu  command  messages,  you  don’t  have  to 
process  the  keystrokes  themselves.  Some  non-Windows  programs  for  the  PC  use  function 
keys  extensively  in  combination  with  the  Shift,  Ctrl,  and  Alt  keys.  You  can  do  something 
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similar  in  your  Windows  programs,  but  it’s  not  recommended.  If  you  want  to  use  the 
function  keys,  they  should  duplicate  menu  commands.  One  objective  in  Windows  is  to  pro¬ 
vide  a  user  interface  that  doesn’t  require  memorization  or  using  complex  command  charts. 

We’ve  managed  to  eliminate  everything  except  one  final  case:  Most  of  the  time,  you 
will  process  WM_KEYDOWN  messages  only  for  cursor  movement  keys.  When  you  use  the 
cursor  keys,  you  can  check  the  Shift-key  and  Ctrl-key  states  through  GetKeyState.  Windows 
functions  often  use  the  Shift  key  in  combination  with  the  cursor  keys  to  extend  a  selection 
in  (for  instance)  a  word-processing  document.  The  Ctrl  key  is  often  used  to  alter  the  mean¬ 
ing  of  the  cursor  key.  (For  example,  Ctrl  in  combination  with  the  Right  Arrow  key  might 
mean  to  move  the  cursor  one  word  to  the  right.) 

One  of  the  best  ways  to  determine  how  to  use  the  keyboard  is  to  examine  how  the 
keyboard  is  used  in  existing  Windows  programs.  If  you  don’t  like  those  definitions,  you 
are  free  to  do  something  different.  But  keep  in  mind  that  doing  so  may  be  detrimental  to 
a  user’s  ability  to  quickly  learn  your  program. 

ENHANCING  SYSMETS: 

ADDING  A  KEYBOARD  INTERFACE 

When  we  wrote  the  three  versions  of  the  SYSMETS  program  in  Chapter  2,  we  didn’t  know 
anything  about  the  keyboard.  We  were  able  to  scroll  the  text  only  by  using  the  mouse  on 
the  scroll  bars.  Now  that  we  know  how  to  process  keystroke  messages,  let’s  add  a  keyboard 
interface  to  SYSMETS.  This  is  obviously  a  job  for  cursor  movement  keys.  We’ll  use  most  of 
the  cursor  movement  keys  (Home,  End,  Page  Up,  Page  Down,  Up  Arrow,  and  Down  Arrow) 
for  vertical  scrolling.  The  Left  Arrow  key  and  the  Right  Arrow  key  can  take  care  of  the  less- 
important  horizontal  scrolling. 

Adding  WM.KEYDOWN  Logic 

One  obvious  way  to  create  a  keyboard  interface  is  to  add  some  WM_KEYDOWN  logic  to 
the  window  procedure  that  parallels  the  WM_VSCROLL  and  WM_HSCROLL  logic: 

case  WM_KEYDOWN  : 

nVscrollInc  =  nHscrollInc  =  0  ; 

switch  (wParam) 

{ 

case  VK_H0ME  :  //  sane  as  WM_VSCROLL,  SB_T0P 

nVscrollInc  =  -nVscrollPos  ; 
break  ; 

case  VK_END  :  //  same  as  WMJ/SCROLL,  SB.BOTTOM 

nVscrollInc  =  nVscrollMax  -  nVscrollPos  ; 
break  ; 
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case  VKJJP  :  //  same  as  WMJ/SCROLL,  SB.LINEUP 

nVscrol line  =  -1  ; 
break  ; 

case  VOOWN  :  //  same  as  WMJ/SCROLL,  SB_L I N EDOWN 

nVscrol 1  Inc  =  1  ; 
break  ; 

case  VK_PRI OR  :  //  same  as  WMJ/SCROLL,  SB.PAGEUP 

nVscrol line  =  min  (-1,  -cyClient  /  cyChar)  ; 
break  ; 

case  V K_N EXT  :  //  same  as  WMJ/SCROLL,  SB_PAGEDOWN 

nVscrol line  =  max  (1,  cyClient  /  cyChar)  ; 
break  ; 

case  V K_LE FT  :  //  same  as  WM.HSCROLL,  SB.PAGEUP 

nHscrol line  =  -8  ; 
break  ; 

case  V K_RI GHT  :  //  same  as  WM.HSCROLL,  SB.PAGEDOWN 

nHscrol 1  Inc  =  8  ; 
break  ; 

default  : 
break  ; 

} 

if  ( nVscrol line  =  max  ( -nVscrol 1 Pos, 

min  (nVscroll Inc,  nVscrollMax  -  nVscrol 1 Pos) ) ) 

{ 

nVscrollPos  +=  nVscrol line  ; 

ScrollWindow  (hwnd,  0,  -cyChar  *  nVscrol line,  NULL,  NULL)  ; 

SetScrol 1 Pos  (hwnd,  SBJ/ERT,  nVscrollPos,  TRUE)  ; 

UpdateWindow  (hwnd)  ; 

} 

if  (nHscrollInc  =  max  ( -nHscrol 1 Pos , 

min  (nHscrollInc,  nHscrollMax  -  nHscrol 1 Pos) ) ) 

{ 

nHscrollPos  +=  nHscrollInc  ; 

ScrollWindow  (hwnd,  -cxChar  *  nHscrollInc,  0,  NULL,  NULL)  ; 

SetScrollPos  (hwnd,  SB_H0RZ,  nHscrollPos,  TRUE)  ; 

} 

return  0  ; 

Do  you  dislike  this  code  as  much  as  I  do?  Simply  duplicating  all  the  scroll  bar  code  is 
unwise,  because  if  we  ever  wanted  to  change  the  scroll  bar  logic,  we’d  have  to  make  paral¬ 
lel  changes  in  WM-KEYDOWN.  There  has  to  be  a  better  way.  And  there  is. 
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Sending  Messages 

Wouldn’t  it  be  better  to  simply  translate  each  of  these  WM_KEYDOWN  messages  into  an 
equivalent  WM_VSCROLL  and  WM_HSCROLL  message  and  then  perhaps  fool  WndProc 
into  thinking  that  it’s  getting  a  WM_VSCROLL  or  WM_HSCROLL  message,  perhaps  by 
sending  a  phony  scroll  bar  message  to  the  window  procedure?  Windows  lets  you  do  this. 
The  function  is  called  SendMessage ,  and  it  takes  the  same  parameters  as  those  passed  to  the 
window  procedure: 

SendMessage  (hwnd,  message,  wParam,  IParam)  ; 

When  you  call  SendMessage ,  Windows  calls  the  window  procedure  whose  window 
handle  is  hwnd ,  passing  to  it  these  four  parameters.  When  the  window  procedure  has  com¬ 
pleted  processing  the  message,  Windows  returns  control  to  the  next  statement  following 
the  SendMessage  call.  The  window  procedure  to  which  you  send  the  message  could  be  the 
same  window  procedure,  another  window  procedure  in  the  same  program,  or  even  a  win¬ 
dow  procedure  in  another  application. 

Here’s  how  we  might  use  SendMessage  for  processing  WM_KEYDOWN  codes  in  the 
SYSMETS  program: 

case  WM.KEYDOWN  : 
switch  (wParam) 

{ 

case  VK.H0ME  : 

SendMessage  (hwnd,  WM_VSCROLL,  SB.TOP,  0L)  ; 
break  ; 

case  VK_END  : 

SendMessage  (hwnd,  WM.VSCROLL,  SB.BOTTOM,  0L)  ; 
break  ; 

case  V K _ PRI OR  : 

SendMessage  (hwnd,  WM.VSCROLL,  SB.PAGEUP,  0L)  ; 
break  ; 

[other program  lines] 

OK,  you  get  the  general  idea.  Our  goal  was  to  add  a  keyboard  interface  to  the  scroll  bars, 
and  that’s  exactly  what  we’ve  done.  We’ve  made  the  cursor  movement  keys  duplicate  scroll 
bar  logic  by  actually  sending  the  window  procedure  a  scroll  bar  message.  Now  you  see 
why  I  included  SB_TOP  and  SB -BOTTOM  processing  for  WM-VSCROLL  messages  in  the 
SYSMETS3  program.  It  wasn’t  used  then,  but  it’s  used  now  for  processing  the  Home  and 
End  keys.  The  final  SYSMETS  program,  shown  in  Figure  3-2,  incorporates  these  changes. 
You’ll  also  need  the  SYSMETS.H  file  from  Chapter  2  (Figure  2-4)  to  compile  this  program. 

Remember :  To  send  a  message  to  a  window  procedure,  use  the  SendMessage  func¬ 
tion.  Do  not  try  to  call  the  window  procedure  directly  like  this: 

WndProc  (hwnd,  WM.VSCROLL,  SB_PAGEUP,  0L)  ;  //  WRONG  !!! 
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Windows  will  terminate  your  program  if  you  try  to  do  this.  You  may  define  and  call  other 
subroutines  within  a  Windows  program,  but  you  must  not  call  a  window  procedure  di¬ 
rectly.  You’ll  find  out  why  in  Chapter  7. 

SYSMETS.MAK 

# . 

#  SYSMETS.MAK  make  file 

#  . 

sysmets.exe  :  sysmets.obj  sysmets.def 

$ (WINLINK)  sysmets,  sysmets,  NUL,  $( WINLIB) .  sysmets 
rc  -t  sysmets.exe 

sysmets.obj  :  sysmets. c  sysmets. h 
$( WINCC)  sysmets. c 


SYSMETS.C 

/* . - . 

SYSMETS.C  --  System  Metrics  Display  Program 
(c)  Charles  Petzold,  1992 
. */ 

^define  WIN31 
#include  <windows.h> 

^include  "sysmets.h" 

#define  min(a.b)  (((a)  <  (b) )  ?  (a)  :  (b) ) 

#define  max(a.b)  (((a)  >  (b) )  ?  (a)  :  (b) ) 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT.  UINT,  LONG)  : 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "SysMets"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

Figure  3-2.  The  SYSMETS  program.  (continued) 
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wndclass.cbWndExtra  =  0  ; 
wndclass.hlnstance  =  hlnstance  ; 

wndclass.hlcon  =  Loadlcon  (NULL,  IDI.APPLICATION)  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
wndclass.lpszMenuName  =  NULL  ; 
wndclass.lpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "System  Metrics”, 

WS.OVERLAPPEDWINDOW  !  WS.VSCROLL  !  WS.HSCROLL, 
CW__US EDE FAU LT ,  CW.USEDEFAULT, 

COSEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  short  cxChar,  cxCaps,  cyChar,  cxClient,  cyClient,  nMaxWidth, 
nVscrollPos,  nVscrollMax,  nHscrollPos,  nHscrollMax  ; 
char  szBuffer[10]  ; 

HDC  hdc  ; 

short  i,  x,  y,  nPaintBeg,  nPaintEnd,  nVscrollInc,  nHscrollInc  ; 

PAINTSTRUCT  ps  ; 

TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 
cxChar  =  tm.tmAveCharWidth  ; 

cxCaps  =  (tm.tmPitchAndFamily  &  1  ?  3  :  2)  *  cxChar  /  2  ; 
cyChar  =  tm.tmHeight  +  tm.tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 


(continued) 


104 


Chapter  3:  The  Keyboard 


nMaxWidth  =  40  *  cxChar  +  22  *  cxCaps  ; 
return  0  ; 

case  WM_SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HIWORD  (IParam)  ; 

nVscrol IMax  =  max  (0,  NUMLINES  +  2  -  cyClient  /  cyChar)  ; 
nVscrollPos  =  min  (nVscrollPos,  nVscrollMax)  ; 

SetScroll Range  (hwnd,  SELVERT,  0,  nVscrollMax.  FALSE)  ; 

SetScrol 1 Pos  (hwnd.  SBJ/ERT,  nVscrollPos,  TRUE)  ; 

nHscrollMax  =  max  (0,  2  +  (nMaxWidth  -  cxClient)  /  cxChar)  ; 
nHscrollPos  =  min  (nHscrollPos,  nHscrollMax)  ; 

SetScroll Range  (hwnd,  SBJiORZ,  0,  nHscrollMax,  FALSE)  ; 

SetScrol 1 Pos  (hwnd,  SB_H0RZ,  nHscrollPos,  TRUE)  ; 
return  0  ; 

case  WM_VSCROLL  : 
switch  (wParam) 

{ 

case  SB_T0P  : 

nVscrollInc  =  -nVscrollPos  ; 
break  ; 

case  SB.BOTTOM  : 

nVscrollInc  =  nVscrollMax  -  nVscrollPos  ; 
break  ; 

case  SB_LINEUP  : 

nVscroll Inc  =  -1  ; 
break  ; 

case  SB_LI NEDOWN  : 

nVscrollInc  =  1  ; 
break  ; 

case  SB_PAGEUP  : 

nVscrollInc  =  min  (-1,  -cyClient  /  cyChar)  ; 
break  ; 

case  SB_PAGEDOWN  : 

nVscrollInc  =  max  (1,  cyClient  /  cyChar)  ; 
break  ; 

case  SB.THUMBTRACK  : 

nVscrollInc  =  LOWORD  (IParam)  -  nVscrollPos  ; 
break  ; 

(continued) 
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default  : 

nVscroll Inc  =  0  ; 

} 

nVscrollInc  =  max  ( -nVscroll Pos , 

min  (nVscrollInc,  nVscrollMax  -  nVscrollPos))  ; 

if  (nVscrollInc  !=  0) 

{ 

nVscrollPos  +=  nVscrollInc  ; 

ScrollWindow  (hwnd,  0,  -cyChar  *  nVscrollInc,  NULL,  NULL)  ; 
SetScrol 1 Pos  (hwnd,  SB.VERT,  nVscrollPos,  TRUE)  ; 
UpdateWindow  (hwnd)  ; 

} 

return  0  ; 

case  WM_HSCROLL  : 

switch  (wParam) 

{ 

case  SELLINEUP  : 

nHscrol 1  Inc  =  -1  ; 
break  ; 

case  SB_LI NEDOWN  : 

nHscroll Inc  =  1  ; 
break  ; 

case  SB.PAGEUP  : 

nHscrollInc  =  -8  ; 
break  ; 

case  SB.PAGEDOWN  : 

nHscrollInc  =  8  ; 
break  ; 

case  SB_THUMBPOS I TI ON  : 

nHscrollInc  =  LOWORD  (IParam)  -  nHscrollPos  ; 
break  ; 

default  : 

nHscrollInc  =  0  ; 

} 

nHscrollInc  =  max  (-nHscrollPos, 

min  (nHscrollInc,  nHscrollMax  -  nHscrollPos))  ; 

if  (nHscrollInc  !=  0) 

{ 

nHscrollPos  +=  nHscrollInc  ; 

ScrollWindow  (hwnd,  -cxChar  *  nHscrollInc,  0,  NULL,  NULL)  ; 
SetScrol  1  Pos  (hwnd,  SB.HORZ,  nHscrollPos,  TRUE)  ; 

} 

return  0  ; 


(continued) 


106 


Chapter  3:  The  Keyboard 


case  WM_KEYDOWN  : 
switch  (wParam) 

{ 

case  VK_H0ME  : 

SendMessage  (hwnd,  WMJ/SCROLL,  SBJTOP,  0L)  ; 
break  ; 

case  VK_END  : 

SendMessage  (hwnd.  WMJ/SCROLL,  SB.BOTTOM,  0L)  ; 
break  ; 

case  VK_PRI0R  : 

SendMessage  (hwnd,  WMJ/SCROLL,  SB_PAGEUP,  0L)  ; 
break  ; 

case  VKJOT  : 

SendMessage  (hwnd.  WMJ/SCROLL.  SB_PAGEDOWN.  0L)  ; 
break  ; 

case  VKJJP  : 

SendMessage  (hwnd.  WM_VSCROLL.  SB_LINEUP,  0L)  ; 
break  ; 

case  VKJ30WN  : 

SendMessage  (hwnd,  WM_VSCROLL,  SB_LI NEDOWN ,  0L)  ; 
break  ; 

case  VK_LEFT  : 

SendMessage  (hwnd,  WM_HSCROLL,  SB.PAGEUP,  0L)  ; 
break  ; 

case  VK_RIGHT  : 

SendMessage  (hwnd.  WM_HSCROLL,  SB_PAGEDOWN,  0L)  ; 
break  ; 

} 

return  0  ; 
case  WM.PAINT  : 

hdc  =  BeginPaint  (hwnd.  &ps)  ; 

nPaintBeg  =  max  (0,  nVscrollPos  +  ps.rcPaint.top  /  cyChar  -  1)  ; 
nPaintEnd  =  min  (NUMLINES, 

nVscrollPos  +  ps.rcPaint. bottom  /  cyChar)  ; 

for  (i  =  nPaintBeg  ;  i  <  nPaintEnd  ;  i++) 

{ 

x  =  cxChar  *  (1  -  nHscrollPos)  ; 
y  =  cyChar  *  (1  -  nVscrollPos  +  i)  ; 

TextOut  (hdc,  x,  y, 

sysmetrics[i].szLabel , 

lstrlen  (sysmetrics[i].szLabel ))  ; 


(continued) 
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TextOut  (hdc,  x  +  22  *  cxCaps,  y, 
sysmetrics[i].szDesc, 
lstrlen  (sysmetrics[i].szDesc))  ; 

SetTextAlign  (hdc,  TA_RIGHT  !  TA_T0P)  ; 

TextOut  (hdc,  x  +  22  *  cxCaps  +  40  *  cxChar,  y, 
szBuffer, 

wsprintf  (szBuffer,  "%5d", 

GetSystemMetrics  (sysmetrics[i].nlndex)))  ; 

SetTextAlign  (hdc,  TA__LEFT  !  TA_T0P)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


SYSMETS.DEF 


SYSMETS.DEF  module  definition  file 


NAME  SYSMETS 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'System  Metrics  Display  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


CHARACTER  MESSAGES 

Earlier  I  discussed  the  idea  of  translating  keystroke  messages  into  character  messages  by 
taking  into  account  shift-state  information,  and  I  warned  that  shift-state  information  is  not 
enough:  You  also  need  to  know  about  country- dependent  keyboard  configurations.  For 
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this  reason,  you  should  not  attempt  to  translate  keystroke  messages  into  character  codes 
yourself. 

Windows  does  it  for  you.  You’ve  seen  this  code  before: 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

This  is  a  typical  message  loop  that  appears  in  WinMain.  The  GetMessage  function  fills  in 
the  msg  structure  fields  with  the  next  message  from  the  queue.  DispatchMessage  calls  the 
appropriate  window  procedure  with  this  message. 

Between  these  two  functions  is  TranslateMessage ,  which  translates  keystroke  mes¬ 
sages  into  character  messages.  If  the  message  is  WM_KEYDOWN  or  WM_SYSKEYDOWN, 
and  if  the  keystroke  in  combination  with  the  shift  states  produces  a  character,  then 
TranslateMessage  places  a  character  message  in  the  message  queue.  This  character  mes¬ 
sage  will  be  the  next  message  that  GetMessage  retrieves  from  the  queue  after  the  keystroke 
message. 


There  are  four  character 

messages: 

Characters 

Dead  Characters 

Nonsystem  Characters: 

WM-CHAR 

WM-DEADCHAR 

System  Characters: 

WM  -SYSCH  AR 

WM-SYSDEADCHAR 

The  WM_CHAR  and  WM_DEADCHAR  messages  are  derived  from  WM_KEYDOWN 
messages.  The  WM-SYSCHAR  and  WM_SYSDEADCHAR  messages  are  derived  from 
WM-SYSKEYDOWN  messages.  In  most  cases,  your  Windows  program  can  ignore  every¬ 
thing  except  WM-CHAR  messages.  The  iParam  parameter  passed  to  the  window  pro¬ 
cedure  with  the  character  code  message  is  the  same  as  the  IParam  parameter  for  the 
keystroke  message  that  generated  the  character  code  message.  The  tuParam  parameter  is 
the  ASCII  code  for  the  character  (yes,  good  old  familiar  ASCII). 

The  character  messages  are  delivered  to  your  window  procedure  sandwiched  be¬ 
tween  keystroke  messages.  For  instance,  if  Caps  Lock  is  not  toggled  on  and  you  press  and 
release  the  A  key,  the  window  procedure  receives  the  following  three  messages: 


Message 

Key  or  Code 

WM-KEYDOWN 

Virtual  key  A 

WM_CHAR 

ASCII  code  a 

WM-KEYUP 

Virtual  key  A 
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If  you  type  an  uppercase  A  by  pressing  the  Shift  key,  pressing  the  A  key,  releasing  the 
A  key,  and  then  releasing  the  Shift  key,  the  window  procedure  receives  five  messages: 


Message  Key  or  Code 

WM-KEYDOWN  Virtual  key  VK-SHIFT 

WM-KEYDOWN  Virtual  key  A 

WM-CHAR  ASCII  code  A 

WM.KEYUP  Virtual  key  A 

WM-KEYUP  Virtual  key  VK-SHIFT 


The  Shift  key  by  itself  does  not  generate  a  character  message. 

If  you  hold  down  the  A  key  so  that  the  typematic  action  generates  keystrokes,  you’ll 
get  a  character  message  for  each  WM_KEYDOWN  message: 


Message 

Key  or  Code 

WM-KEYDOWN 

Virtual  key  A 

WM_CHAR 

ASCII  code  a 

WM-KEYDOWN 

Virtual  key  A 

WM_CHAR 

ASCII  code  a 

WM-KEYDOWN 

Virtual  key  A 

WM-CHAR 

ASCII  code  a 

WM-KEYDOWN 

Virtual  key  A 

WM_CHAR 

ASCII  code  a 

WM-KEYUP 

Virtual  key  A 

If  some  of  the  WM_KEYDOWN  messages  have  a  Repeat  Count  greater  than  1,  the  corre¬ 
sponding  WM_CHAR  messages  will  have  the  same  Repeat  Count. 

The  Ctrl  key  in  combination  with  a  letter  key  generates  ASCII  control  codes  from  01H 
(Ctrl-A)  through  1AH  (Ctrl-Z).  You  can  also  use  other  keys  to  generate  these  control  codes. 
The  following  table  shows  the  value  of  wParam  in  a  WM-CHAR  message  for  keys  that 
generate  control  codes: 


Key 

ASCII  Code 

Duplicated  by 

Backspace 

08H 

Ctrl-H 

Tab 

09H 

Ctrl-I 

Ctrl-Enter 

OAh 

Ctrl-J 

Enter 

ODh 

Ctrl-M 

Esc 

1BH 

Ctrl-[ 
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Windows  programs  sometimes  use  the  Ctrl  key  in  combination  with  letter  keys  for  menu 
accelerators,  in  which  case  the  letter  keys  are  not  translated  into  character  messages. 

WM.CHAR  Messages 

When  your  Windows  program  needs  to  process  characters  from  the  keyboard  (for  in¬ 
stance,  in  a  word-processing  or  communications  program),  it  will  process  WM_CHAR 
messages.  You’ll  probably  want  some  special  processing  for  the  Backspace,  Tab,  and  Enter 
keys  (and  perhaps  the  Linefeed  key),  but  you’ll  treat  all  other  characters  the  same: 

case  WM.CHAR  : 

switch  (wParam) 

{ 

case  ' \b *  :  //  backspace 

[other program  lines] 
break  ; 

case  '\t'  :  //  tab 

[other program  lines] 
break  ; 

case  ' \n *  :  //  linefeed 

[other program  lines] 
break  ; 

case  ’ \r '  :  //  carriage  return 

[other program  lines] 
break  ; 

default  :  //  character  code 

[other program  lines] 
break  ; 

} 

return  0  ; 

This  program  fragment  is  virtually  identical  to  keyboard  character  processing  in  regular 
MS-DOS  programs. 

Dead-Character  Messages 

Windows  programs  can  usually  ignore  WM-DEADCHAR  and  WM_SYSDEADCHAR  mes¬ 
sages.  On  some  non-U.S.  keyboards,  certain  keys  are  defined  to  add  a  diacritic  to  a  letter. 
These  are  called  “dead  keys”  because  they  don’t  create  characters  by  themselves.  For  in¬ 
stance,  when  the  German  keyboard  is  installed,  the  key  that  is  in  the  same  position  as  the 
+/=  key  on  a  U.S.  keyboard  is  a  dead  key  for  the  acute  accent  C )  when  unshifted  and  the 
grave  accent  C)  when  shifted. 
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When  a  user  presses  this  dead  key,  your  window  procedure  receives  a 
WM_DEADCHAR  message  with  wParam  equal  to  the  ASCII  code  for  the  diacritic  by  itself. 
When  the  user  then  presses  a  letter  key  (for  instance,  the  A  key),  the  window  procedure 
receives  a  WM_CHAR  message  where  wParam  is  the  ASCII  code  for  the  letter  a  with  the 
diacritic.  Thus,  your  program  does  not  have  to  process  the  WM-DEADCHAR  message,  be¬ 
cause  the  WM_CHAR  message  gives  the  program  all  the  information  it  needs.  The  Win¬ 
dows  logic  even  has  built-in  error  handling:  If  the  dead  key  is  followed  by  a  letter  that  can’t 
take  a  diacritic  (such  as  the  letter  s),  then  the  window  procedure  receives  two  WM_CHAR 
messages  in  a  row — the  first  with  wParam  equal  to  the  ASCII  code  for  the  diacritic  by  itself 
(the  same  wParam  value  delivered  with  the  WM_DEADCHAR  message)  and  the  second 
with  wParam  equal  to  the  ASCII  code  for  the  letter  s. 


LOOKING  AT  KEYBOARD  MESSAGES 

If  you’d  like  to  see  how  Windows  sends  keyboard  messages  to  a  program,  KEYLOOK 
(shown  in  Figure  3-3)  will  help.  This  program  displays  in  its  client  area  all  the  information 
that  Windows  sends  the  window  procedure  for  the  eight  different  keyboard  messages. 


KEYLOOK.MAK 

# . 

#  KEYLOOK.MAK  make  file 

# 

keylook.exe  :  keylook.obj  keylook.def 

$ ( WINLI NK)  keylook,  keylook,  NUL,  $(WINLIB),  keylook 
rc  -t  keylook.exe 

keylook.obj  :  keylook. c 
$ ( W I NCC )  keylook. c 


KEYLOOK.C 

/* . - . . 

KEYLOOK.C  --  Displays  Keyboard  and  Character  Messages 
(c)  Charles  Petzold,  1992 

.  . */ 


#include  <windows.h> 

#include  <stdio.h> 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


Figure  3-3.  The  KEYLOOK  program. 
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RECT  rect  ; 

short  cxChar,  cyChar  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  lpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "KeyLook"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS_HREDRAW  !  CSJ/REDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

wndclass. cbWndExtra  =  0  ; 

wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  Loadlcon  (NULL,  IDI_APPLICATION)  ; 

wndclass. hCursor  =  LoadCursor  (NULL,  I DC_ARR0W )  ; 

wndclass. hbrBackground  =  (HBRUSH)  GetStockObject  (WHITE_BRUSH)  ; 
wndclass. IpszMenuName  =  NULL  ; 
wndclass. IpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Keyboard  Message  Looker", 

WS_OVERLAPP EDWIN DOW, 

CW_USEDEFAULT,  CWJJSEDEFAULT, 

CW_USEDEFAULT,  CW_USEDE FAULT , 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg ,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  ShowKey  (HWND  hwnd,  int  i Type .  char  *szMessage,  UINT  wParam,  LONG  lParam) 

{ 

static  char  *szFormat[2]  =  {  "%-14s  %3d  %c  %6u  %4d  %3s  %3s  %4s  %4s", 

"%-14s  %3d  %c  %6u  %4d  %3s  %3s  %4s  %4s"  }  ; 

char  szBuffer[80]  ; 

HDC  hdc  ; 
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ScrollWindow  (hwnd,  0,  -cyChar,  &rect,  &rect)  ; 
hdc  =  GetDC  (hwnd)  ; 


SelectObject  (hdc.  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 


TextOut  (hdc.  cxChar,  rect. bottom  -  cyChar.  szBuffer. 
wsprintf  (szBuffer,  szFormat  [ i Type] , 

(LPSTR)  szMessage,  wParam, 

(BYTE)  (iType  ?  wParam  :  '  '), 


LOWORD  (1  Pa  ram), 

H I WORD  (IParam)  &  0xFF, 

(LPSTR)  (0X01000000  &  IParam  ? 

(LPSTR)  (0X20000000  &  IParam  ? 

(LPSTR)  (0x40000000  &  IParam  ? 

(LPSTR)  (0x80000000  &  IParam  ? 


Yes" 

:  "No"), 

Yes" 

:  "No"), 

Down" 

:  "Up"), 

Up" 

:  "Down"))) 

ReleaseDC  (hwnd,  hdc)  ; 
ValidateRect  (hwnd,  NULL)  ; 
} 


long  FAR  PASCAL  _export  WndProc 
{ 

static  char  szTop[]  = 
"Message 

static  char  szUnd[]= 


HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM_CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc.  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

GetTextMetrics  (hdc,  &tm)  ; 
cxChar  =  tm. tmAveCharWidth  ; 
cyChar  =  tm.tmHeight  ; 

ReleaseDC  (hwnd,  hdc)  ; 

rect. top  =  3  *  cyChar  /  2  ; 
return  0  ; 

case  WM_SIZE  : 

rect. right  =  LOWORD  (IParam)  ; 
rect. bottom  =  HIWORD  (IParam)  ; 

UpdateWindow  (hwnd)  ; 
return  0  ; 


(HWND  hwnd,  UINT  message,  UINT  wParam. 

LONG  IParam) 


Key  Char  Repeat  Scan  Ext  ALT  Prev  Tran" 
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case  WM_PAI NT  : 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
hdc  =  BeginPaint  (hwnd.  &p$)  ; 

SelectObject  (hdc.  GetStockObject  ( SYSTEM_FI XED_F0NT) )  ; 
SetBkMode  (hdc.  TRANSPARENT)  ; 

TextOut  (hdc,  cxChar,  cyChar  /  2,  szTop,  (sizeof  szTop)  -  1)  ; 
TextOut  (hdc,  cxChar,  cyChar  /  2,  szUnd,  (sizeof  szUnd)  -  1)  ; 
EndPaint  (hwnd,  &ps)  ; 
return  0  ; 


case  WM_KEYDOWN  : 

ShowKey  (hwnd,  0,  "WM.KEYDOWN",  wParam,  IParam)  ; 
return  0  ; 


case  WM_KEYUP  : 

ShowKey  (hwnd,  0,  **WM_KEYUPM ,  wParam,  IParam)  ; 
return  0  ; 

case  WM_CHAR  : 

ShowKey  (hwnd,  1,  "WM_CHARn ,  wParam,  IParam)  ; 
return  0  ; 

case  WM_DEADCHAR  : 

ShowKey  (hwnd,  1,  "WM_DEADCHAR",  wParam,  IParam)  ; 
return  0  ; 


case  WM.SYSKEYDOWN  : 

ShowKey  (hwnd,  0,  "WM_SYSKEYDOWN" ,  wParam,  IParam)  ; 
break  ;  //  ie,  call  DefWindowProc 


case  WM.SYSKEYUP  : 

ShowKey  (hwnd,  0,  "WM_SYSKEYUPM,  wParam,  IParam)  ; 
break  ;  //  ie,  call  DefWindowProc 


case  WM_SY SCHAR  : 

ShowKey  (hwnd,  1,  "WM_SYSCHAR",  wParam,  IParam)  ; 
break  ;  //  ie,  call  DefWindowProc 


case  WM_SYSDEADCHAR  : 

ShowKey  (hwnd,  1,  "WM_SYSDEADCHAR" ,  wParam,  IParam)  ; 
break  ;  //  ie,  call  DefWindowProc 


case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
} 
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KEYLOOK.DEF 


KEYLOOK.DEF  module  definition  file 


NAME  KEYLOOK 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


’Key  Look  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

’WINSTUB.EXE’ 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


KEYLOOK  uses  the  display  like  an  old-fashioned  teletype  output  device.  When  KEYLOOK 
receives  a  keystroke  message,  it  calls  ScrollWindow  to  scroll  the  contents  of  the  entire  cli¬ 
ent  area  of  the  window  so  that  the  contents  move  up  the  height  of  one  character.  TextOut 
is  used  to  display  the  line  of  new  information  beginning  one  character  height  from  the 
bottom.  This  is  about  as  simple  as  a  teletype  output  can  get.  Figure  3-4  shows  what  the 
KEYLOOK  display  looks  like  when  you  type  the  word  “Windows.”  The  first  column  shows 
the  keyboard  message,  the  second  shows  the  virtual  key  code  for  keystroke  messages,  the 
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Figure  3-4.  The  KEYLOOK  display . 
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third  shows  the  character  code  (and  the  character  itself)  for  character  messages,  and  the 
other  six  columns  show  the  states  of  the  six  fields  in  the  iParam  message  parameter. 

Most  of  KEYLOOK.C  uses  features  of  Windows  that  have  already  been  covered  in  the 
various  SYSMETS  programs,  but  a  few  new  functions  are  used  here. 

The  column  formatting  of  KEYLOOK  would  be  difficult  with  the  default  proportional 
font.  The  code  to  display  each  line  would  need  to  be  broken  into  nine  sections  to  get  every¬ 
thing  lined  up.  For  something  like  this,  a  much  easier  approach  is  to  simply  switch  to  a 
fixed-pitch  font.  This  requires  two  functions  in  a  single  statement: 

SelectObject  (hdc.  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

KEYLOOK  calls  these  two  functions  whenever  it  obtains  a  device  context.  This  oc¬ 
curs  in  three  places:  the  ShowKey  function,  while  processing  the  WM_CREATE  message  in 
WndProc,  and  while  processing  the  WM_PAINT  message.  The  GetStockObject  function 
obtains  a  handle  to  a  “stock”  graphics  object,  which  is  a  predefined  graphics  object  that 
Windows  makes  available  to  programs.  In  this  case,  GetStockObject  obtains  a  handle  to  a 
font  known  as  SYSTEM_FIXED_FONT,  which  is  the  fixed-pitch  font  that  was  used  in  ver¬ 
sions  of  Windows  prior  to  Windows  3.  The  SelectObject  call  selects  that  object  into  the  de¬ 
vice  context.  Following  this  call,  all  text  that  is  displayed  will  use  the  fixed-pitch  font.  It  is 
possible  to  switch  back  to  the  default  proportional  font  by  calling: 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FONT) )  ; 

I’ll  discuss  these  functions  in  more  depth  in  Chapter  12. 

The  ShowKey  function  calls  ScrollWindow  to  scroll  the  previous  lines  of  keystrokes 
up  before  displaying  a  new  line.  Normally  this  would  cause  part  of  the  window  to  become 
invalid  and  hence  generate  a  WM_PAINT  message.  The  ShowKey  function  concludes  with 
a  call  to  ValidateRect  to  prevent  this. 

Notice  the  use  of  the  Windows  wsprintf  function  in  the  ShowKey  function.  The  char¬ 
acter  strings  must  be  explicitly  cast  to  far  pointers  using  the  LPSTR  data  type  (defined  in 
WINDOWS.H  as  a  far  pointer  to  a  character  string).  The  wsprintf  function  is  one  of  the 
very  few  functions  in  Windows  that  explicitly  requires  casting  of  its  parameters. 

KEYLOOK  does  not  save  the  keystrokes  it  receives,  so  on  receipt  of  a  WM -PAINT 
message  it  cannot  re-create  the  window.  For  this  reason,  KEYLOOK  simply  displays  the 
header  at  the  top  of  the  client  area  during  the  WM-PAINT  message.  Before  calling  Begin- 
Paint  during  the  WM_PAINT  message,  KEYLOOK  invalidates  the  entire  window.  This 
allows  the  whole  window  to  be  erased  rather  than  just  the  invalid  rectangle. 

(That  KEYLOOK  does  not  save  the  keystrokes  and  hence  cannot  redraw  the  window 
during  a  WM -PAINT  message  is  certainly  a  flaw.  The  TYPE  program  shown  later  in  this 
chapter  corrects  this  flaw.) 

KEYLOOK  draws  a  header  at  the  top  of  the  client  area  identifying  the  nine  columns. 
Although  it’s  possible  to  create  an  underlined  font,  I  took  a  slightly  different  approach 
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here.  I  defined  two  character  string  variables  named  szTop  (which  has  the  text)  and  szUnd 
(which  has  the  underlining)  and  displayed  both  of  them  at  the  same  position  at  the  top  of 
the  window  during  the  WM_PAINT  message.  Normally,  Windows  displays  text  in  an 
“opaque”  mode,  meaning  that  Windows  erases  the  character  background  area  while  dis¬ 
playing  a  character.  This  would  cause  the  second  character  string  ( szUnd )  to  erase  the  first 
(. szTop ).  To  prevent  this,  switch  the  device  context  into  the  “transparent”  mode: 

SetBkMode  (hdc,  TRANSPARENT)  ; 

THE  CARET  (NOT  THE  CURSOR) 

When  you  type  text  into  a  program,  generally  a  little  underline  or  box  shows  you  where 
the  next  character  you  type  will  appear  on  the  screen.  You  may  know  this  as  a  “cursor,”  but 
you’ll  have  to  get  out  of  that  habit  when  programming  for  Windows.  In  Windows,  it’s  called 
the  “caret.”  The  word  “cursor”  is  used  for  the  bitmap  image  that  represents  the  mouse 
position. 

The  Caret  Functions 

There  are  five  essential  caret  functions: 

■  CreateCaret — creates  a  caret  associated  with  a  window. 

■  SetCaretPos — sets  the  position  of  the  caret  on  the  window. 

■  ShowCaret — shows  the  caret. 

■  HideCaret — hides  the  caret. 

■  DestroyCaret — destroys  the  caret. 

There  are  also  functions  to  get  the  caret  position  ( GetCaretPos )  and  to  get  and  set  the  caret 
blink  time  (GetCaretBlinkTime  and  SetCaretBlinkTime). 

The  caret  is  customarily  a  horizontal  line  or  a  box  that  is  the  size  of  a  character  or  a 
vertical  line.  The  vertical  line  is  recommended  when  you  use  a  proportional  font  such  as 
the  Windows  default  system  font.  Because  the  characters  in  a  proportional  font  are  not  a 
fixed  size,  the  horizontal  line  and  box  can’t  be  set  to  the  size  of  a  character. 

You  cannot  simply  create  a  caret  during  the  WM -CREATE  message  and  destroy  it 
during  the  WM-DESTROY  message.  The  caret  is  what  is  known  as  a  “systemwide 
resource.”  What  this  means  is  that  there  is  only  one  caret  in  the  system.  In  effect,  a  pro¬ 
gram  “borrows”  the  caret  from  the  system  when  it  needs  to  display  a  caret  in  its  window. 

Does  this  sound  bizarrely  restrictive?  It’s  really  not.  Think  about  it:  The  display  of  a 
caret  in  a  window  makes  sense  only  when  the  window  has  the  input  focus.  This  indicates 
to  the  user  that  he  or  she  may  enter  text  in  the  program.  Only  one  window  has  the  input 
focus  at  any  time,  so  only  one  caret  is  needed  in  the  whole  system. 
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A  program  can  determine  if  it  has  the  input  focus  by  processing  the  WM_SETFOCUS 
and  WM-KILLFOCUS  messages.  A  window  procedure  receives  a  WM_SETFOCUS  mes¬ 
sage  when  it  receives  the  input  focus,  and  a  WM_KILLFOCUS  message  when  it  loses  the 
input  focus.  These  messages  occur  in  pairs:  A  window  procedure  will  always  receive  a 
WM_SETFOCUS  message  before  it  receives  a  WM_KILLFOCUS  message,  and  it  always 
receives  an  equal  number  of  WM_SETFOCUS  and  WM_KILLFOCUS  messages  over  the 
course  of  the  window’s  lifetime. 

The  main  rule  for  using  the  caret  is  simple:  A  window  procedure  calls  CreateCaret 
during  the  WM_SETFOCUS  message  and  DestroyCaret  during  the  WM_KILLFOCUS 
message. 

There  are  a  few  other  rules:  The  caret  is  created  hidden.  After  calling  CreateCaret , 
the  window  procedure  must  call  ShowCaret  for  the  caret  to  be  visible.  In  addition,  the  win¬ 
dow  procedure  must  hide  the  caret  by  calling  HideCaret  whenever  it  draws  something  on 
its  window  during  a  message  other  than  WM_PAINT.  After  it  finishes  drawing  on  the  win¬ 
dow,  it  calls  ShowCaret  to  display  the  caret  again.  The  effect  of  HideCaret  is  additive:  If 
you  call  HideCaret  several  times  without  calling  ShowCaret ,  you  must  call  ShowCaret  the 
same  number  of  times  before  the  caret  becomes  visible  again. 

The  TYPE  Program 

The  TYPE  program  shown  in  Figure  3-5  (beginning  on  the  following  page)  brings  together 
much  of  what  we’ve  learned  in  this  chapter.  You  can  think  of  TYPE  as  an  extremely  rudi¬ 
mentary  text  editor.  You  can  type  in  the  window,  move  the  cursor  (I  mean  caret)  around 
with  the  cursor  movement  (or  are  they  caret  movement?)  keys,  and  erase  the  contents  of 
the  window  by  pressing  Escape.  The  contents  of  the  window  are  also  erased  when  you  re¬ 
size  the  window.  There’s  no  scrolling,  no  search  and  replace,  no  way  to  save  files,  and  no 
spell  checker,  but  it’s  a  start. 

To  make  things  easy  for  myself,  TYPE  uses  SYSTEM_FIXED_FONT.  Writing  a  text 
editor  for  a  proportional  font  is,  as  you  might  imagine,  much  more  difficult.  The  program 
obtains  a  device  context  in  several  places:  during  the  WM_CREATE  message,  the 
WM_KEYDOWN  message,  the  WM_CHAR  message,  and  the  WM-PAINT  message.  Each 
time,  calls  to  GetStockObject  and  SelectObject  select  the  fixed-pitch  font. 

During  the  WM_SIZE  message,  TYPE  calculates  the  character  width  and  height  of 
the  window  and  saves  these  values  in  the  variables  cxBuffer  and  cyBuffer.  It  then  uses 
malloc  to  allocate  a  buffer  to  hold  all  the  characters  that  can  be  typed  in  the  window.  The 
xCaret  and  yCaret  variables  store  the  character  position  of  the  caret. 

During  the  WM_SETFOCUS  message,  TYPE  calls  CreateCaret  to  create  a  caret  that  is 
the  width  and  height  of  a  character,  SetCaretPos  to  set  the  caret  position,  and  ShowCaret  to 
make  the  caret  visible.  During  the  WM_KILLFOCUS  message,  TYPE  calls  HideCaret  and 
DestroyCaret. 
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TYPE.MAK 

# . - . 

//  TYPE.MAK  make  file 

# . 

type.exe  :  type.obj  type.def 

$(WINLINK)  type,  type,  NUL,  $(WINLIB),  type 
rc  -t  type.exe 

type.obj  :  type.c 
$ ( W I NCC )  type.c 


TYPE.C 

/* . 

TYPE.C  --  Typing  Program 

(c)  Charles  Petzold,  1992 

. */ 

//include  <windows.h> 

//include  <stdlib.h> 

//define  min(a.b)  (((a)  <  (b))  ?  (a)  :  (b)) 

//define  max(a.b)  (((a)  >  (b))  ?  (a)  :  (b) ) 

//define  BUFFER(x.y)  *(pBuffer  +  y  *  cxBuffer  +  x) 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Type”  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

wndclass. cbWndExtra  =  0  ; 

wndclass. hlnstance  =  hlnstance  ; 

Figure  3-5.  The  TYPE  program.  (continued) 
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wndclass.hlcon  =  Loadlcon  (NULL.  IDI__APPLICATION)  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 
wndclass.hbrBackground  =  (HBRUSH)  GetStockObject  (WHITE.BRUSH)  ; 
wndclass.lpszMenuName  =  NULL  ; 
wndclass.lpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Typing  Program", 

WS_0V  ERLAP P EDW I NDOW . 

CW.USEDEFAULT,  CWJJSEDE FAULT, 

CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL.  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  char  *pBuffer  =  NULL  ; 

static  int  cxChar,  cyChar,  cxClient,  cyClient,  cxBuffer,  cyBuffer, 
xCaret,  yCaret  ; 

HDC  hdc  ; 

int  x,  y,  i  ; 

PAINTSTRUCT  ps  ; 

TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 
GetTextMetrics  (hdc,  &tm)  ; 
cxChar  =  tm.tmAveCharWidth  ; 
cyChar  =  tm.tmHeight  ; 

ReleaseDC  (hwnd,  hdc)  ; 
return  0  ; 


(continued) 
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case  WM.SIZE  : 

//  obtain  window  size  in  pixels 

cxClient  =  LOWORD  (lParam)  ; 
cyClient  =  HIWORD  ( 1  Pa  ram)  ; 

//  calculate  window  size  in  characters 

cxBuffer  =  max  (1,  cxClient  /  cxChar)  ; 
cyBuffer  =  max  (1,  cyClient  /  cyChar)  ; 

//  allocate  memory  for  buffer  and  clear  it 


if  (pBuffer  !=  NULL) 
free  (pBuffer)  ; 

if  ((LONG)  cxBuffer  *  cyBuffer  >  65535L  !! 

(pBuffer  =  (char  *)  malloc  (cxBuffer  *  cyBuffer))  ==  NULL) 


else 

for 


MessageBox  (hwnd,  "Window  too  large.  Cannot  " 

"allocate  enough  memory.",  "Type", 
MB_I CONEXCLAMATI ON  !  MB_0K)  ; 

(y  =  0  ;  y  <  cyBuffer  ;  y++) 
for  (x  =  0  ;  x  <  cxBuffer  ;  x++) 

BUFFER(x,y )  =  '  '  ; 


//  set  caret  to  upper  left  corner 

xCaret  =  0  ; 
yCaret  =  0  ; 


if  (hwnd  ==  GetFocus  0) 

SetCaretPos  (xCaret  *  cxChar,  yCaret  *  cyChar)  ; 
return  0  ; 


case  WM_SETFOCUS  : 


//  create  and  show  the  caret 


CreateCaret  (hwnd,  NULL,  cxChar,  cyChar)  ; 
SetCaretPos  (xCaret  *  cxChar,  yCaret  *  cyChar)  ; 
ShowCaret  (hwnd)  ; 
return  0  ; 

case  WM_KI LLFOCUS  : 

//  hide  and  destroy  the  caret 

HideCaret  (hwnd)  ; 

DestroyCaret  0  ; 
return  0  ; 


(continued) 
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case  WM.KEYDOWN  : 
switch  (wParam) 

{ 

case  VK.H0ME  : 
xCaret  =  0  ; 
break  ; 

case  VK_END  : 

xCaret  =  cxBuffer  -  1  ; 
break  ; 

case  V K_P RI OR  : 
yCaret  =  0  ; 
break  ; 

case  VK_NEXT  : 

yCaret  =  cyBuffer  -  1  ; 
break  ; 

case  VK_LE FT  : 

xCaret  =  max  (xCaret  -1,0); 
break  ; 

case  VK_RIGHT  : 

xCaret  =  min  (xCaret  +  1,  cxBuffer  -  1)  ; 
break  ; 

case  V K _ UP  : 

yCaret  =  max  (yCaret  -1,0); 
break  ; 

case  VK_D0WN  : 

yCaret  =  min  (yCaret  +  1,  cyBuffer  -  1)  ; 
break  ; 

case  VK_DELETE  : 

for  (x  =  xCaret  ;  x  <  cxBuffer  -  1  ;  x++) 

BUFFER  (x,  yCaret)  =  BUFFER  (x  +  1,  yCaret)  ; 

BUFFER  (cxBuffer  -  1,  yCaret)  =  '  ’  ; 

HideCaret  (hwnd)  ; 
hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc, 

GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

TextOut  (hdc,  xCaret  *  cxChar,  yCaret  *  cyChar, 


(continued) 
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&  BUFFER  (xCaret,  yCaret), 
cxBuffer  -  xCaret)  ; 

ShowCaret  (hwnd)  ; 

ReleaseDC  (hwnd,  hdc)  ; 
break  ; 


SetCaretPos  (xCaret  *  cxChar,  yCaret  *  cyChar)  ; 
return  0  ; 

case  WM.CHAR  : 

for  (i  =  0  ;  i  <  (int)  LOWORD  (lParam)  ;  i++) 

{ 

switch  (wParam) 

{ 

case  '\b'  :  //  backspace 

if  (xCaret  >  0) 

{ 

xCaret--  ; 

SendMessage  (hwnd,  WM_KEYDOWN, 
VK_DELETE,  1L)  ; 

} 

break  ; 

case  • \t ’  :  //  tab 

do 

{ 

SendMessage  (hwnd,  WM_CHAR,  1  \  1L)  ; 

} 

while  (xCaret  %  8  !=  0)  ; 
break  ; 

case  ' \n'  :  //  linefeed 

if  (++yCaret  ==  cyBuffer) 
yCaret  =  0  ; 
break  ; 

case  * \r *  :  //  carriage  return 

xCaret  =  0  ; 

if  (++yCaret  ==  cyBuffer) 
yCaret  =  0  ; 
break  ; 

case  '\xlB'  :  //  escape 

for  (y  =  0  ;  y  <  cyBuffer  ;  y++) 

for  (x  =  0  ;  x  <  cxBuffer  ;  x++) 

BUFFER  (x,  y)  =  '  ’  ; 


(continued) 


124 


Chapter  3:  The  Keyboard 


xCaret  =  0  ; 
yCaret  =  0  ; 

Inval idateRect  (hwnd,  NULL,  FALSE)  ; 
break  ; 

default  :  //  character  codes 

BUFFER  (xCaret,  yCaret)  =  (char)  wParam  ; 

HideCaret  (hwnd)  ; 
hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc, 

GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

TextOut  (hdc,  xCaret  *  cxChar,  yCaret  *  cyChar, 
&  BUFFER  (xCaret,  yCaret),  1)  ; 

ShowCaret  (hwnd)  ; 

ReleaseDC  (hwnd,  hdc)  ; 

if  (++xCaret  ==  cxBuffer) 

{ 

xCaret  =  0  ; 

if  (++yCaret  ==  cyBuffer) 
yCaret  =  0  ; 

} 

break  ; 

} 

} 

SetCaretPos  (xCaret  *  cxChar,  yCaret  *  cyChar)  ; 
return  0  ; 

case  WM_PA I  NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

for  (y  =  0  ;  y  <  cyBuffer  ;  y++) 

TextOut  (hdc,  0,  y  *  cyChar,  &  BUFFER(0,y) ,  cxBuffer)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 


(continued) 
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return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


TYPE.DEF 


TYPE. DEF  module  definition  file 


NAME 


TYPE 


DESCRIPTION  'Typing  Program  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


The  processing  of  the  WM _KE YDOWN  and  WM_CHAR  messages  is  more  extensive. 
The  WM_KE YDOWN  processing  mostly  involves  the  cursor  movement  keys.  Home  and 
End  send  the  caret  to  the  beginning  and  end  of  a  line,  and  Page  Up  and  Page  Down  send 
the  caret  to  the  top  and  bottom  of  the  window.  The  arrow  keys  work  as  you  would  expect. 
For  the  Delete  key,  TYPE  must  move  everything  remaining  in  the  buffer  from  the  next  caret 
position  to  the  end  of  the  line  and  then  display  a  blank  at  the  end  of  the  line. 

The  WM_CHAR  processing  handles  the  Backspace,  Tab,  Linefeed  (Ctrl-Enter),  Enter, 
Escape,  and  character  keys.  Notice  Eve  used  Repeat  Count  in  IParam  when  processing  the 
WM_CHAR  message  (under  the  assumption  that  every  character  the  user  types  is  impor¬ 
tant)  but  not  during  the  WM_KE YDOWN  message  (to  prevent  inadvertent  oversc rolling). 
The  Backspace  and  Tab  processing  is  simplified  somewhat  by  the  use  of  the  SendMessage 
function.  Backspace  is  emulated  by  the  Delete  logic,  and  Tab  is  emulated  by  a  series  of 
spaces. 

As  I  mentioned  earlier,  you  should  hide  the  cursor  when  drawing  on  the  window 
during  messages  other  then  WM -PAINT.  The  program  does  this  when  processing  the 
WM_KE YDOWN  message  for  the  Delete  key  and  the  WM-CHAR  message  for  character 
keys.  In  both  these  cases,  TYPE  alters  the  contents  of  the  buffer  and  then  draws  the  new 
character  or  characters  on  the  window. 

I  use  TYPE  when  working  on  speeches,  as  shown  in  Figure  3-6. 
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Typing  Program 


um 


Fourscore  and  seuen  years  ago  our  fathers  brought  forth  on  this  continent  a 
new  nation  conceiued  in  liberty  and  dedicated  to  the  proposition  that  all 
men  are  created  equal.  Now  we  are  engaged  in  a  great  ciuil  war  testing 
whether  that  nation,  or  any  nation  so  conceiued  and  so  dedicated,  can  long 
endure.  We  are  met  on  a  great  battlefield  of  that  war.  We  haue  come  to 
dedicate  a  portion  of  that  field  as  a  final  resting-place  for  those  who  here 
gaue  their  liues  that  that  nation  might  liue.  It  is  altogether  fitting  and 
proper  that  we  should  do  this.  But,  in  a  larger  sense,  we  cannot  dedicate, 
cannot  consecrate,  we  cannot  hallow  this  ground.  The  braue  men,  liuing 
and  dead,  who  struggled  here  haue  consecrated  it  far  aboue  our  poor  power  to 
add  or  detract.  The  world  will  little  note  nor  long  remember  what  we  say 
here,  but  it  can  neuer  forget  what  they  did  here.  It  is  for  us  the  liuing 
rather  to  be  dedicated  here  to  the  unfinished  work  which  they  who  fought 
here  haue  thus  far  so  nobly  aduanced.  It  is  rather  for  us  to  be  here 
dedicated  to  the  great  task  remaining  before  us — that  from  these  honored 
dead  we  take  increased  deuotion  to  that  cause  for  which  they  gaue  their  last 
full  measure  of  deuotion — that  we  here  highly  resolue  that  these  dead  shall 
not  haue  died  in  uain,  that  this  nation  under  God  shall  haue  a  new  birth  of 
freedom,  and  that  gouernment  of  the  people,  by  the  people,  for  the  people 
shall'  not  perish  from  the  earth.  [ 


k 


Figure  3-6.  The  TYPE  display. 


THE  WINDOWS  CHARACTER  SETS 

I  mentioned  earlier  that  letter  keys  preceded  by  dead-character  keys  generate  WM_CHAR 
messages  where  wParam  is  the  ASCII  code  for  a  character  with  a  diacritic.  This  may  be  a 
little  puzzling  because  the  ASCII  character  set  doesn’t  include  any  codes  for  characters 
with  diacritics.  What  exactly  is  the  value  of  wParam  in  this  case?  The  answer  to  this  ques¬ 
tion  requires  that  we  tackle  the  subject  of  character  sets,  a  topic  that  may  at  first  seem  more 
appropriate  for  a  later  discussion  about  character  fonts.  However,  it  is  also  of  vital  impor¬ 
tance  in  keyboard  handling. 

The  standard  7-bit  ASCII  character  set  defines  codes  from  0  through  31  (OxlF)  and  127 
(0x7F)  as  control  characters,  and  it  defines  codes  from  32  (0x20)  through  126  (0x7E)  as  dis- 
playable  characters.  None  of  these  characters  have  diacritics.  Because  personal  computers 
use  8-bit  bytes,  computer  manufacturers  often  define  character  sets  that  use  256  codes 
rather  than  the  128  ASCII  codes.  The  additional  codes  may  be  assigned  characters  with 
diacritics.  The  resultant  “extended  character  set”  then  includes  the  ASCII  character  set  and 
up  to  128  other  characters. 

If  Windows  supported  such  an  extended  character  set,  displaying  characters  with 
diacritics  would  be  easy.  But  Windows  doesn’t  support  a  simple  extended  character  set. 
Windows  supports  two  extended  character  sets.  Unfortunately,  the  presence  of  these  two 
character  sets  doesn’t  make  things  twice  as  easy. 
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The  OEM  Character  Set 

First,  let’s  go  back  to  the  hardware  that  Windows  runs  on — the  IBM  PC  and  compatibles.  In 
the  early  1980s,  the  developers  of  the  IBM  PC  decided  to  extend  the  ASCII  character  set  as 
shown  in  Figure  3-7.  The  codes  from  0x20  through  0x7E  are  displayable  characters  from 
the  ASCII  character  set.  The  rest  are  nonstandard — or  at  least  were  at  the  time. 

This  character  set  cannot  be  ignored.  It  is  encoded  in  millions  of  ROM  chips  in  IBM 
video  adapters,  printers,  and  system  board  BIOS’s.  It  has  been  duplicated  in  the  hardware 
of  numerous  manufacturers  of  IBM-compatible  computers  and  peripherals.  This  character 
set  is  part  of  what  is  meant  by  the  phrase  “the  IBM  standard.”  Many  non-Windows  text¬ 
mode  programs  written  for  the  IBM  PC  require  this  extended  character  set  because  they 
use  the  block-drawing  and  line-drawing  characters  (codes  BOP!  through  DFH)  in  their 
screen  output. 

01  23456789ABCDEF 

00  @QV  +  44*Qo[*]6l$J1J1# 

io:  M  t  !!  H  §  .  It  1  -n-  ^  «  i  T 

20 

so:  0123456789  :  ;<=>? 
40PABCDEFGHIJKLMNO 

so  :  p  q  n  i  u  u  w  n  z  [  \  ]  A  _ 

6°:  abcdef  ghijklnno 

70:pqrstuuwxyz<  !  >  "  ^ 

80:pueaaaapeee  x  1  1  A  H 

90:£se(E6oouuiioUC£¥&J 
AO:  a  i  6  u  ii  N  a  2  i  r  1  Ji  i  «» 

B0  i  i  i  I  M  II  n  =1  II  II  71  u  J  n 

co  L  ^  t  V  ~  +  N  II  *  n  i-1  i?  \\  =  it  ± 

DO:  u  —  n  u  b  F  IT  II  T  J  T  ■  .  I  I  " 

EMtpriEajiTHDfif0f  n 

F0:E±><  f  J  t  S  °  ■  -  sT  11  2  I 

Figure  3-7.  The  IBM  extended  character  set  arranged  by  character  code. 
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The  only  problem  is  this:  The  IBM  extended  character  set  is  inappropriate  for  Win¬ 
dows.  First,  the  block-drawing  and  line-drawing  characters  commonly  used  by  PC  pro¬ 
grams  in  text-mode  applications  are  not  needed  in  Windows  because  Windows  does  real 
graphics.  If  you  want  to  draw  a  horizontal  line  in  Windows,  it’s  easier  to  draw  a  line  than  to 
display  a  string  of  0xC4  characters.  Second,  the  Greek  alphabet  and  mathematical  symbols 
are  less  important  in  Windows  than  are  the  accented  letters  used  in  most  European  lan¬ 
guages.  A  program  that  needs  to  display  mathematical  symbols  can  best  draw  them  using 
graphics  functions. 

In  short,  Windows  supports  the  IBM  character  set,  but  it  is  relegated  to  secondary  im¬ 
portance — mostly  for  old  applications  that  run  in  a  window.  Windows  applications  do  not 
normally  use  the  IBM  character  set.  In  Windows  documentation,  the  IBM  character  set  is 
referred  to  as  the  “OEM  character  set.”  The  OEM  character  set  is  more  precisely  defined  as 
the  character  set  that  is  native  to  the  machine  currently  running  Windows. 

International  support  under  DOS 

There  are  a  number  of  variants  on  the  IBM  PC  character  set,  called  “code  pages.”  The 
variant  used  in  the  United  States  and  in  most  European  countries  is  called  Code  Page  437. 
Systems  sold  in  Norway,  Denmark,  Portugal,  and  a  few  other  European  countries  use  dif¬ 
ferent,  special,  code  pages,  which  contain  more  of  the  special  characters  required  by  the 
languages  of  those  countries.  Recently,  a  number  of  these  countries  began  to  use  Code  Page 
850,  which  contains  fewer  graphics  symbols  and  more  accented  letters  and  other  special 
characters. 

Windows  3.0  supports  code  pages  by  installing  OEM  fonts  (used  for  running  DOS  ap¬ 
plications  in  windows  and  in  the  clipboard  viewer),  which  correspond  to  the  system’s  code 
page,  and  by  installing  appropriate  translation  tables  for  the  AnsiToOem  and  OemToAnsi 
functions  (discussed  later).  If  the  system  is  running  DOS  version  3.3  or  later,  the  Windows 
Setup  program  will  use  the  current  DOS  code  page.  For  earlier  versions  of  DOS,  Setup  will 
select  a  code  page  based  on  the  localized  (national)  version  of  Windows. 

The  ANSI  Character  Set 

The  extended  character  set  that  Windows  and  Windows  programs  use  for  most  purposes  is 
called  the  “ANSI  character  set.”  When  your  program  receives  a  WM_CHAR  message,  the 
wParam  parameter  is  the  ANSI  character  code.  The  ANSI  character  set  is  shown  in  Figure 
3-8  on  the  following  page.  As  you  can  see,  the  codes  from  0x20  through  0x7E  represent 
the  same  characters  that  appear  in  the  OEM  character  set  and  the  ASCII  character  set.  The 
characters  displayed  as  solid  blocks  are  undefined  characters.  They  may  appear  differently 
on  other  output  devices  (such  as  a  printer).  TrueType  fonts  (discussed  in  Chapter  14) 
define  some  additional  characters  for  ANSI  codes  0x80  through  0x9F. 
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Figure  3-8.  The  ANSI  character  set  arranged  by  character  code. 

OEM,  ANSI,  and  Fonts 

Windows  has  different  fonts  for  displaying  the  ANSI  and  OEM  character  sets.  When  you 
first  obtain  a  handle  to  a  device  context,  one  of  the  attributes  in  the  device  context  is  a  font. 
By  default  this  is  the  SYSTEM_FONT  or  “system  font,”  which  uses  the  ANSI  character 
set.  If  you  want  to  display  characters  from  the  OEM  character  set,  you  can  select  the 
OEM_FIXED_FONT  (also  called  the  “terminal  font”)  in  the  device  context  by  using  the 
following  code: 

SelectObject  (hdc,  GetStockObject  (0EM_FIXED_F0NT) )  ; 

Other  fonts  support  the  OEM  character  set,  as  I’ll  discuss  in  Chapter  14. 
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INTERNATIONALIZATION  CONCERNS 

Here’s  why  we  have  to  talk  about  fonts  in  the  middle  of  the  keyboard  chapter.  We’ve  estab¬ 
lished  that  when  a  Windows  user  on  a  non-U.S.  keyboard  types  a  character  with  a  diacritic, 
the  tuParam  parameter  of  the  WM_CHAR  message  is  the  code  for  that  character  in  the 
ANSI  character  set. 

So,  if  you  need  to  echo  that  character  to  the  display,  you  had  better  be  using  a  font 
with  the  ANSI  character  set  (such  as  the  SYSTEM-FONT  or  SYSTEM -FIXED -FONT).  If 
you  instead  use  the  OEM_FIXED_FONT,  the  character  you  write  to  the  display  will  be 
incorrect  and  will  surprise  the  user.  A  few  other  simple  rules  will  allow  the  keyboard  logic 
in  your  Windows  programs  to  survive  intact  when  you  convert  your  programs  for  a  Euro¬ 
pean  market. 

Working  with  the  Character  Set 

When  you  get  a  WM-CHAR  message,  keep  in  mind  that  wParam  may  legitimately  have 
values  above  128.  Don’t  assume  that  anything  above  127  is  an  invalid  character. 

You  may  want  to  convert  a  character  to  uppercase.  Don’t  use  your  own  algorithm: 

if  (ch  >=  'a'  &&  ch  <=  '  z' ) 

ch  -=  32  ;  //  WRONG  !!! 

That’s  a  poor  practice  even  when  writing  non-Windows  C.  But  don’t  use  the  standard  C 
function  either: 

ch  =  toupper  (ch)  ;  //  WRONG  !!! 

Both  these  functions  work  only  for  the  lower  half  of  the  ANSI  character  set.  They  will  not 
convert  a  OxEO  to  a  OxCO. 

Instead,  you  should  use  the  Windows  functions  AnsiUpper  and  AnsiLower.  If  str  is  a 
zero -terminated  character  string,  you  can  convert  it  to  uppercase  using  AnsiUpper : 

AnsiUpper  (pString)  ; 

or  using  the  AnsiUpperBuff  function  for  character  strings  that  are  not  O-terminated: 
AnsiUpperBuff  (pString,  nLength)  ; 

You  can  also  use  AnsiUpper  to  convert  a  single  character,  but  some  casting  is  required  be¬ 
cause  the  high-order  word  of  the  parameter  must  be  0: 

ch  =  AnsiUpper  ( ( LPSTR)  (LONG)  (BYTE)  ch)  ; 

If  ch  is  defined  as  an  unsigned  character,  the  initial  BYTE  cast  is  not  required.  Windows 
also  includes  AnsiLower  and  AnsiLowerBuff  functions  for  converting  to  lowercase. 
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If  you  are  really  serious  about  writing  Windows  programs  that  can  be  easily  con¬ 
verted  to  foreign  languages,  you  should  also  investigate  the  AnsiNext  and  AnsiPrev  func¬ 
tions.  These  functions  facilitate  handling  of  multibyte  character  sets.  The  Japanese 
character  set  requires  more  than  256  characters,  some  of  which  use  2  bytes.  If  you  use  nor¬ 
mal  C  pointer  arithmetic  to  scan  a  string  (perhaps  searching  for  a  backslash  character  in  a 
directory  path  string),  you  may  think  you’ve  found  the  character  when  you’ve  really  found 
the  second  byte  of  a  2-byte  character  code.  AnsiNext  and  AnsiPrev  take  a  far  pointer  to  a 
character  string  and  return  a  far  pointer  that  has  been  correctly  incremented  or  decre¬ 
mented  past  2-byte  character  codes. 

Talking  with  MS-DOS 

If  Windows  were  the  only  operating  environment  running  on  a  machine,  then  you  could 
forget  about  the  OEM  character  set  and  use  only  the  ANSI  character  set.  However,  users 
can  create  files  in  the  MS-DOS  environment  and  use  them  in  Windows;  they  can  also 
create  files  in  Windows  and  use  them  when  back  in  MS-DOS.  Unfortunately,  MS-DOS  uses 
the  OEM  character  set. 

Here’s  an  example  of  the  communications  problems  that  can  occur.  Suppose  that  a 
German-speaking  PC  user  creates  a  file  named  UBUNGEN.TXT  (“practice  exercises”)  in 
an  MS-DOS  program  such  as  EDLIN.  On  the  IBM  PC,  the  U  is  part  of  the  IBM  (that  is,  OEM) 
character  set  and  has  a  code  of  154  or  0x9A.  (When  using  MS-DOS  with  a  U.S.  keyboard  on 
an  IBM  PC,  you  can  also  create  this  letter  by  typing  Alt-154  using  the  numeric  keypad.) 
MS-DOS  uses  that  character  code  in  the  directory  entry  of  the  file. 

If  a  Windows  program  uses  MS-DOS  function  calls  to  obtain  a  directory  of  files  and 
then  writes  them  directly  to  the  display  using  an  ANSI  character  set  font,  the  first  letter  of 
UBUNGEN  will  show  up  as  a  solid  block,  because  the  code  154  is  one  of  the  undefined 
characters  in  the  ANSI  character  set.  The  Windows  program  needs  to  convert  the  IBM  ex¬ 
tended  character  set  code  of  154  (0x9A)  to  an  ANSI  character  set  code  of  220  (or  DCH), 
which  is  the  letter  U  in  the  ANSI  character  set.  That’s  what  the  Windows  function 
OemToAnsi  does  for  you.  It  requires  two  far  pointers  to  strings.  The  OEM  characters  in  the 
first  string  are  converted  to  ANSI  characters  and  stored  in  the  second  string: 

OemToAnsi  (1 pszOemStr ,  IpszAnsiStr)  ; 

Now  let’s  take  the  opposite  example.  The  German-speaking  user  wants  your  Win¬ 
dows  program  to  create  a  file  named  UBUNGEN.TXT.  The  filename  entered  by  the  user 
has  a  220  (OxDC)  as  the  first  character.  If  you  use  an  MS-DOS  function  call  to  open  the  file, 
MS-DOS  uses  that  character  in  the  filename.  When  the  user  later  looks  at  the  file  under  MS- 
DOS,  the  first  character  shows  up  as  a  block.  Before  you  use  the  MS-DOS  function  calls, 
you  must  convert  the  filename  to  the  OEM  character  set: 

AnsiToOem  (IpszAnsiStr,  IpszOemStr)  ; 
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This  converts  a  220  (OxDC)  to  a  154  (0x9A).  Windows  also  includes  two  functions  named 
AnsiToOemBuff  and  OemToAnsiBuff  that  do  not  require  a  0-terminated  string. 

Windows  has  an  OpenFile  call  that  will  convert  this  for  you.  If  you  use  OpenFile ,  don’t 
do  your  own  AnsiToOem  conversion.  If  you  use  MS-DOS  function  calls  to  obtain  lists  of 
filenames  (as  the  Windows  File  Manager  program  does),  then  these  filenames  should  be 
passed  through  OemToAnsi  before  being  displayed. 

Converting  the  contents  of  files  is  another  problem  that  arises  when  files  are  used  in 
both  Windows  and  MS-DOS.  If  your  Windows  program  uses  files  that  you  are  certain  have 
been  created  in  an  MS-DOS  program,  then  you  may  need  to  pass  the  text  contents  of  the 
file  through  the  OemToAnsi  function.  (For  instance,  Windows  WRITE  does  this  when  con¬ 
verting  Microsoft  Word  files  to  WRITE  format.)  Similarly,  if  your  Windows  program  is  pre¬ 
paring  a  file  for  use  in  an  MS-DOS  program,  you  may  want  to  use  AnsiToOem  to  convert 
the  text. 

The  OemToAnsi  and  AnsiToOem  functions  are  located  in  the  keyboard  driver.  They 
incorporate  very  simple  lookup  tables.  The  OemToAnsi  routine  converts  an  OEM  code 
from  0x80  through  OxFF  to  a  character  code  in  the  ANSI  set  that  most  closely  resembles  the 
OEM  character.  In  some  cases,  this  conversion  is  only  grossly  approximate.  For  instance, 
most  of  the  line-drawing  characters  in  the  IBM  character  set  are  translated  as  plus  signs, 
dashes,  and  vertical  lines.  Most  of  the  OEM  codes  from  0x00  through  OxlF  are  not  trans¬ 
lated  to  ANSI  codes. 

The  AnsiToOem  routine  converts  ANSI  codes  from  OxAO  through  OxFF  into  codes  in 
the  OEM  set.  The  accented  characters  in  the  ANSI  character  set  that  do  not  appear  in  the 
OEM  character  set  are  translated  into  regular  ASCII  codes  for  the  characters,  without  the 
diacritics. 

Using  the  Numeric  Keypad 

As  you  probably  know,  the  IBM  PC  keyboard  and  BIOS  let  you  enter  codes  for  the  IBM  ex¬ 
tended  character  set  by  pressing  and  holding  down  the  Alt  key,  typing  on  the  numeric 
keypad  the  three-digit  decimal  code  representing  the  OEM  character,  and  releasing  the  Alt 
key.  This  facility  is  duplicated  in  Windows  in  two  ways. 

First,  when  you  type  Alt -[OEM  code ]  on  the  numeric  keypad,  Windows  gives  you  the 
ANSI  character  code  (in  the  wParam  parameter  of  the  WM_CHAR  message)  that  most 
closely  approximates  the  OEM  character  represented  by  the  OEM  code.  That  is,  Windows 
passes  the  code  through  the  OemToAnsi  function  before  generating  the  WM-CHAR  mes¬ 
sage.  This  facility  is  for  the  user’s  convenience:  If  you  do  not  have  a  foreign-language 
keyboard  and  you  are  accustomed  to  typing  a  U  by  typing  Alt-154,  you  can  do  the  same 
thing  in  a  Windows  program.  You  don’t  need  to  relearn  the  ANSI  character  codes. 

Second,  if  you  want  to  generate  ANSI  extended  character  codes  from  the  U.S.  key¬ 
board,  type  Alt-0  [OEM  code ]  on  the  numeric  keypad.  The  wParam  parameter  of  the 
WM-CHAR  message  is  that  OEM  code.  Thus,  Alt-0220  is  also  a  U.  You  can  try  this  out  in 
the  KEYLOOK  or  TYPE  programs. 
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The  mouse  is  a  pointing  device  with  one  or  more  buttons.  Although  a  mouse  is  considered 
an  important  part  of  Windows’  user  interface,  it  is  an  optional  accessory.  You  can  install 
Windows  without  a  mouse,  and  you  can  control  most  Windows  programs  entirely  from  the 
keyboard.  Often  the  most  difficult  aspect  of  using  the  mouse  in  your  program  is  adding  a 
keyboard  interface  to  duplicate  the  mouse  functions. 

MOUSE  BASICS 

Windows  can  support  a  one-button,  two-button,  or  three-button  mouse  or  use  a  joystick  or 
light  pen  to  mimic  a  one-button  mouse.  Because  a  one-button  mouse  is  the  lowest  com¬ 
mon  denominator,  many  Windows  programmers  avoid  the  use  of  the  second  and  third  but¬ 
tons.  However,  the  two -button  mouse  has  become  the  de  facto  standard,  so  the  traditional 
reticence  to  use  the  second  button  is  no  longer  justified. 

You  can  determine  if  a  mouse  is  present  by  using  the  GetSystemMetrics  function: 

fMouse  =  GetSystemMetrics  ( S M_M OUSEPRESENT)  ; 

The  value  of  fMouse  will  be  TRUE  (nonzero)  if  a  mouse  is  installed.  No  method  is  docu¬ 
mented  for  determining  the  number  of  buttons  on  the  installed  mouse. 

Some  Quick  Definitions 

When  the  Windows  user  moves  the  mouse,  Windows  moves  a  small  bitmapped  picture 
called  the  “mouse  cursor”  on  the  display.  The  mouse  cursor  has  a  single-pixel  “hot  spot” 
that  points  to  a  precise  location  on  the  display. 
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The  display  driver  contains  several  predefined  mouse  cursors  that  programs  may 
use.  The  most  common  is  the  slanted  arrow  called  IDC-ARROW  in  WINDOWS.H.  The  hot 
spot  is  the  tip  of  the  arrow.  The  IDC -CROSS  cursor  (used  in  the  BLOWUP1  program  shown 
in  this  chapter)  has  a  hot  spot  in  the  center  of  a  cross-hair  pattern.  The  IDC-WAIT  cursor  is 
an  hourglass  generally  used  by  programs  to  indicate  they  are  busy.  Programmers  can  also 
design  their  own  cursors  (as  we’ll  do  in  Chapter  8).  The  default  cursor  for  a  particular  win¬ 
dow  is  specified  when  defining  the  window  class  structure.  For  instance: 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

The  following  terms  describe  the  actions  you  take  with  mouse  buttons: 

■  Clicking — pressing  and  releasing  a  mouse  button 

■  Double-clicking — pressing  and  releasing  a  mouse  button  twice  in  quick 
succession 

■  Dragging — moving  the  mouse  while  holding  down  a  button 

On  a  three-button  mouse,  the  buttons  are  called  the  left  button,  middle  button,  and 
right  button.  Mouse-related  identifiers  defined  in  WINDOWS.H  use  the  abbreviations 
LBUTTON,  MBUTTON,  and  RBUTTON.  A  two -button  mouse  has  only  a  left  button  and  a 
right  button.  The  single  button  on  a  one-button  mouse  is  a  left  button. 


CLIENT-AREA  MOUSE  MESSAGES 

In  the  previous  chapter  you  saw  how  Windows  sends  keyboard  messages  only  to  the  win¬ 
dow  with  the  input  focus.  Mouse  messages  are  different:  A  window  procedure  receives 
mouse  messages  whenever  the  mouse  passes  over  the  window  or  is  clicked  within  the  win¬ 
dow,  even  if  the  window  is  not  active  or  does  not  have  the  input  focus.  Windows  defines  21 
messages  for  the  mouse.  However,  11  of  these  messages  do  not  relate  to  the  client  area 
(hereinafter,  “nonclient-area”  messages),  and  Windows  programs  usually  ignore  them. 

When  the  mouse  is  moved  over  the  client  area  of  a  window,  the  window  procedure 
receives  the  message  WM-MOUSEMOVE.  When  a  mouse  button  is  pressed  or  released 
within  the  client  area  of  a  window,  the  window  procedure  receives  these  messages: 


Button 

Pressed 

Released 

Pressed  (Second  Click) 

Left 

WM  -LBUTTON  DOWN 

WM-LBUTTONUP 

WM -LBUTTON DBLCLK 

Middle 

WM  -MBUTTON  DOWN 

WM-MBUTTONUP 

WM -MBUTTON  DBLCLK 

Right 

WM-RBUTTONDOWN 

WM-RBUTTONUP 

WM-RBUTTONDBLCLK 
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Your  window  procedure  receives  “MBUTTON”  messages  only  for  a  three-button 
mouse  and  “RBUTTON”  messages  only  for  a  two -button  or  three-button  mouse.  The  win¬ 
dow  procedure  receives  “DBLCLK”  (double-click)  messages  only  if  the  window  class  has 
been  defined  to  receive  them  (as  described  below). 

For  all  these  messages,  the  value  of  iParam  contains  the  position  of  the  mouse.  The 
low  word  is  the  x-coordinate,  and  the  high  word  is  the  jy-coordinate  relative  to  the  upper 
left  corner  of  the  client  area  of  the  window.  You  can  extract  the  .^-coordinate  and  ^-coordi¬ 
nate  from  IParam  using  the  LOWORD  and  HIWORD  macros  defined  in  WINDOWS.H. 
The  value  of  wParam  indicates  the  state  of  the  mouse  buttons  and  the  Shift  and  Ctrl  keys. 
You  can  test  wParam  using  the  bit  masks  defined  in  WINDOWS.H.  The  MK  prefix  stands 
for  “mouse  key.” 


MK-LBUTTON 
MK-MBUTTON 
MK -RBUTTON 
MK-SHIFT 
MK-CONTROL 


Left  button  is  down 
Middle  button  is  down 
Right  button  is  down 
Shift  key  is  down 
Ctrl  key  is  down 


As  you  move  the  mouse  over  the  client  area  of  a  window,  Windows  does  not  gener¬ 
ate  a  WM-MOUSEMOVE  message  for  every  possible  pixel  position  of  the  mouse.  The  num¬ 
ber  of  WM_MOUSEMOVE  messages  your  program  receives  depends  on  the  mouse 
hardware  and  on  the  speed  at  which  your  window  procedure  can  process  the  mouse 
movement  messages.  You’ll  get  a  good  idea  of  the  rate  of  WM_MOUSEMOVE  messages 
when  you  experiment  with  the  CONNECT  program  described  below. 

If  you  click  the  left  mouse  button  in  the  client  area  of  an  inactive  window,  Windows 
changes  the  active  window  to  the  window  that  is  being  clicked  and  then  passes  the 
WM_LBUTTONDOWN  message  to  the  window  procedure.  When  your  window  procedure 
gets  a  WM_LBUTTONDOWN  message,  your  program  can  safely  assume  the  window  is  ac¬ 
tive.  However,  your  window  procedure  can  receive  a  WM_LBUTTONUP  message  without 
first  receiving  a  WM-LBUTTONDOWN  message.  This  can  happen  if  the  mouse  button  is 
pressed  in  one  window,  moved  to  your  window,  and  released.  Similarly,  the  window  pro¬ 
cedure  can  receive  a  WM_LBUTTONDOWN  without  a  corresponding  WM_LBUTTONUP 
message  if  the  mouse  button  is  released  while  positioned  over  another  window. 

There  are  two  exceptions  to  these  rules: 

■  A  window  procedure  can  “capture  the  mouse”  and  continue  to  receive 
mouse  messages  even  when  the  mouse  is  outside  the  window’s  client 
area.  You’ll  learn  how  to  capture  the  mouse  later  in  this  chapter. 

■  If  a  system  modal  message  box  or  a  system  modal  dialog  box  is  on  the 
display,  no  other  program  can  receive  mouse  messages.  System  modal 
message  boxes  and  dialog  boxes  prohibit  switching  to  another  window  or 
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program  while  the  box  is  active.  (An  example  of  a  system  modal  message 
box  is  the  one  that  says  “This  will  end  your  Windows  session”  when  you 
close  the  Program  Manager.) 

Simple  Mouse  Processing:  An  Example 

The  CONNECT  program,  shown  in  Figure  4-1,  does  some  simple  mouse  processing  to  let 
you  get  a  good  feel  for  how  Windows  sends  mouse  messages  to  your  program. 


CONNECT.MAK 

# . 

#  CONNECT.MAK  make  file 

#  . . 

connect.exe  :  connect. obj  connect. def 

$(WINLINK)  connect,  connect,  NUL,  $( WINLIB) ,  connect 
rc  -t  connect.exe 

connect. obj  :  connect. c 
$ ( W I NCC )  connect. c 


CONNECT.C 

/* . 

CONNECT.C  --  Connect-the-Dots  Mouse  Demo  Program 
(c)  Charles  Petzold,  1992 
. */ 


#i ncl ude  <windows.h> 

#define  MAXPOINTS  1000 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Connect"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


Figure  4-1 .  The  CONNECT  program. 


(continued) 
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if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass  .IpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbrBackg round 
wndclass. IpszMenuName 
wndclass. lpszClassName 


CS_HREDRAW  !  CSJ/REDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  IDI_APPLICATION)  ; 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITEJ3RUSH)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 

} 


hwnd  =  CreateWindow  (szAppName,  "Connect-the-Dots  Mouse  Demo", 
WS_0V  ERLAPPEDW I NDOW , 

CW.USEDEFAULT,  CW.USEDEFAULT, 
CW.USEDEFAULT,  CWJJSEDEFAULT. 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0.  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  ^export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  POINT  poi nts [MAXPOI NTS]  ; 
static  short  nCount  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 
short  i ,  j  ; 

switch  (message) 

{ 

case  WM_LBUTT0ND0WN  : 
nCount  =  0  ; 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 


(continued) 
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case  WM.MOUSEMOVE  : 

if  (wParam  &  MK_LBUTTON  &&  nCount  <  1000) 

{ 

points  [nCount++]  =  MAKEPOINT  ( 1  Pa  ram )  ; 
hdc  =  GetDC  (hwnd)  ; 

SetPixel  (hdc,  LOWORD  (lParam).  HIWORD  (IParam),  0L) 
ReleaseDC  (hwnd,  hdc)  ; 

} 

return  0  ; 

case  WM_LBUTTONUP  : 

InvalidateRect  (hwnd,  NULL,  FALSE)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

for  (i  =  0  ;  i  <  nCount  -  1  ;  i++) 
for  (j  =  i  ;  j  <  nCount  ;  j++) 

{ 

MoveTo  (hdc,  points[i].x,  points[i].y)  ; 

LineTo  (hdc,  points[j].x,  points[j].y)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


CONNECT.DEF 


9 

;  CONNECT.DEF  module  definition  file 


NAME  CONNECT 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 
STACKS I ZE 


'Mouse  Connect  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 
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CONNECT  processes  three  mouse  messages: 

■  WM_LBUTTONDOWN— CONNECT  clears  the  client  area. 

■  WM-MOUSEMOVE — If  the  left  button  is  down,  CONNECT  draws  a  black 
dot  on  the  client  area  at  the  mouse  position. 

■  WM_LBUTTONUP — CONNECT  connects  every  dot  drawn  in  the  client 
area  to  every  other  dot.  Sometimes  this  results  in  a  pretty  design, 
sometimes  in  a  dense  blob.  (See  Figure  4-2.) 

To  use  CONNECT,  bring  the  mouse  cursor  into  the  client  area,  press  the  left  button, 
move  the  mouse  around  a  little,  and  release  the  left  button.  CONNECT  works  best  for  a 
curved  pattern  of  a  few  dots,  which  you  can  draw  by  moving  the  mouse  quickly  while  the 
left  button  is  depressed.  CONNECT  uses  several  simple  Graphics  Device  Interface  (GDI) 
functions.  SetPixel  draws  a  one-pixel  dot  of  a  particular  color — in  this  case  black.  (On 
high-resolution  displays,  the  pixel  may  be  nearly  invisible.)  Drawing  the  lines  requires  two 
functions:  MoveTo  marks  the  x-coordinate  and  ^-coordinate  of  the  beginning  of  the  line, 
and  LineTo  draws  the  line. 

If  you  move  the  mouse  cursor  out  of  the  client  area  before  releasing  the  button,  CON¬ 
NECT  does  not  connect  the  dots  because  it  doesn’t  receive  the  WM_LBUTTONUP  mes¬ 
sage.  If  you  move  the  mouse  back  into  the  client  area  and  press  the  left  button  again, 
CONNECT  clears  the  client  area.  (If  you  want  to  continue  a  design  after  releasing  the 


Figure  4-2.  The  CONNECT  display. 
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button  outside  the  client  area,  press  the  left  button  again  while  the  mouse  is  outside  the  cli¬ 
ent  area  and  then  move  the  mouse  back  inside.) 

CONNECT  stores  a  maximum  of  1000  points.  The  number  of  lines  it  draws  is  equal  to: 

(P)x(P-l) 

2 

where  P  is  the  number  of  points.  With  1000  points,  this  involves  almost  500,000  lines, 
which  can  take  several  minutes  to  draw.  For  anything  but  a  demonstration  program,  this  is 
too  long  for  a  Windows  program  to  hog  system  resources. 

If  CONNECT  is  busy  drawing  lines,  you  can  press  the  mouse  button,  move  the  mouse 
around,  and  release  the  mouse  button,  but  nothing  will  happen.  CONNECT  does  not 
receive  these  messages  because  it  is  busy  and  not  making  any  GetMessage  calls.  After 
CONNECT  finishes  drawing  the  lines,  it  does  not  receive  these  messages  because  the 
mouse  button  has  been  released  already.  In  this  respect,  the  mouse  is  not  like  the  key¬ 
board.  Windows  treats  every  keystroke  as  if  it  were  important.  However,  if  a  mouse  button 
is  pressed  and  released  in  the  client  area  while  a  program  is  busy,  the  mouse  clicks  are 
discarded. 

Now  try  this:  While  CONNECT  is  engaged  in  a  lengthy  drawing  routine,  hold  down 
the  mouse  button  and  move  the  mouse  around.  After  CONNECT  is  finished  drawing,  it  will 
retrieve  the  WM_LBUTTONDOWN  message  from  the  queue  (and  clear  the  client  area) 
because  the  button  is  currently  down.  However,  it  receives  only  the  WM_MOUSEMOVE 
messages  that  occur  after  it  receives  the  WM_LBUTTONDOWN  message. 

Sometimes  the  word  “tracking”  is  used  to  refer  to  the  way  that  programs  process 
mouse  movement.  Tracking  does  not  mean,  however,  that  your  program  sits  in  a  loop  in  its 
window  procedure  attempting  to  follow  the  mouse’s  movements  on  the  display.  The  win¬ 
dow  procedure  instead  processes  each  mouse  message  as  it  comes  and  then  quickly  exits. 

POINT,  RECT,  and  IParam 

CONNECT  uses  an  array  of  POINT  structures  for  saving  points.  The  POINT  structure  is 
defined  in  WINDOWS. H  and  has  two  fields  named  x  and  y: 

typedef  struct  tagPOI NT 

{ 

int  x  ; 
int  y  ; 

} 

POINT  ; 

Some  Windows  functions  require  a  POINT  structure  (or  a  pointer  to  a  POINT  structure)  as 
a  parameter.  You  can  define  a  POINT  structure  variable  (named  point ,  for  instance)  in  your 
program  with  this  definition: 

POINT  point  ; 
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If  you  need  to  convert  an  IParam  value — the  x  and  y  mouse  coordinates — to  a 
POINT  structure,  you  can  use  the  MAKEPOINT  macro: 

point  =  MAKEPOINT  (IParam)  ; 

In  WINDOWS.H,  MAKEPOINT  is  defined  like  this: 

#define  MAKEPOI NT ( 1 )  (*( ( POINT  *)&D) 

Despite  the  apparent  complexity  of  this  macro,  it  compiles  very  efficiently  because  all  it 
does  is  store  IParam  at  the  address  of  point.  WINDOWS.H  defines  the  type  PPOINT  as  a 
pointer  to  a  POINT  structure,  so  perhaps  this  statement  (without  using  the  macro)  makes 
the  conversion  a  little  clearer: 

point  =  *  (PPOINT)  SlParam  ; 

(Remember  that  standard  C  order-of-evaluation  rules  cause  address,  indirection,  and  type 
cast  operators  to  be  evaluated  from  right  to  left.) 

The  RECT  structure  defines  a  rectangle.  Here’s  the  WINDOWS.H  definition: 

typedef  struct  tagRECT 
{ 

int  left  ; 
int  top  ; 
int  right  ; 
int  bottom  ; 

} 

RECT  ; 

This  structure  really  contains  two  points  side  by  side:  left  and  right  are  x-coordinates,  and 
top  and  bottom  are  jy-coordinates.  You  can  define  a  structure  variable  (named  rect,  for 
instance)  with  the  statement: 

RECT  rect  ; 

Transferring  coordinates  from  a  RECT  structure  to  a  POINT  structure  is  also  straight¬ 
forward.  This  statement  sets  point  to  the  upper  left  corner  of  the  rectangle: 

point  =  *  (PPOINT)  &rect.left  ; 

This  does  the  same  for  the  lower  right  corner: 

point  =  *  (PPOINT)  &rect. right  ; 

You  can  also  define  an  array  of  two  points: 

POINT  points  [2]  ; 

and  transfer  these  two  points  into  a  RECT  structure: 
rect  =  *  (PRECT)  points  ; 

PRECT  is  defined  in  WINDOWS.H  as  a  pointer  to  a  RECT  structure.  You  don’t  need  the  & 
(address)  operator  before  points  because  points  is  an  array,  and  the  array  name  is  the 
address  of  the  first  element  of  the  array. 
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Processing  Shift  Keys 

When  CONNECT  receives  a  WM_MOUSEMOVE  message,  it  performs  a  bitwise  AND 
operation  on  the  value  of  wParam  and  MK_LBUTTON  to  determine  if  the  left  button  is 
depressed.  You  can  also  use  wParam  to  determine  the  state  of  the  Shift  keys.  For  instance, 
if  processing  must  be  dependent  on  the  status  of  the  Shift  and  Ctrl  keys,  you  might  use 
logic  that  looks  like  this: 

if  ( MK _ SH I  FT  &  wParam) 

if  (MK_C0NTR0L  &  wParam) 

{ 

[Shift  and  Ctrl  keys  are  down] 

} 

else 

{ 

[Shift  key  is  down] 

} 

else  if  (MK_C0NTR0L  &  wParam) 

{ 

[Ctrl  key  is  down] 

} 

else 

{ 

[neither  Shift  nor  Ctrl  key  is  down] 

} 

If  you  want  to  use  both  the  left  and  right  mouse  buttons  in  your  programs,  and  if  you 
also  want  to  accommodate  those  users  with  a  one-button  mouse,  you  can  write  your  code 
so  that  Shift  in  combination  with  the  left  button  is  equivalent  to  the  right  button.  In  that 
case,  your  mouse  button-click  processing  might  look  something  like  this: 

case  WM_LBUTT0ND0WN  : 

if  ( ! MK_SH I  FT  &  wParam) 

{ 

[left  button  logic] 

return  0  ; 

} 

//  fall  through 

case  WM.RBUTTONDOWN  : 

[right  button  logic] 

return  0  ; 

The  Windows  function  GetKeyState  (described  in  Chapter  3)  can  also  return  the 
status  of  the  mouse  buttons  or  shift  keys  using  the  virtual  key  codes  VK_LBUTTON, 
VK_RBUTTON,  VK_MBUTTON,  VK.SHIFT,  and  VK.CONTROL.  The  button  or  key  is 
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down  if  the  value  returned  from  GetKeyState  is  negative.  Because  GetKeyState  returns 
mouse  or  key  states  as  of  the  message  currently  being  processed,  the  status  information  is 
properly  synchronized  with  the  messages.  But  just  as  you  cannot  use  GetKeyState  for  a  key 
that  has  yet  to  be  pressed,  so  you  cannot  use  it  for  a  mouse  button  that  has  yet  to  be  pressed. 
Don’t  do  this: 

while  (GetKeyState  (VK_LBUTTON)  >=  0)  ;  //  WRONG  !!! 

The  GetKeyState  function  will  report  that  the  left  button  is  depressed  only  if  the  button  is 
already  depressed  when  you  process  the  message  during  which  you  call  GetKeyState . 

Mouse  Double-Clicks 

A  mouse  double-click  is  two  clicks  in  quick  succession.  To  qualify  as  a  double-click,  the 
two  clicks  must  occur  in  close  proximity  within  a  specific  interval  called  the  “double-click 
time.”  If  you  want  your  window  procedure  to  receive  double-click  mouse  messages,  you 
must  include  the  identifier  CS-DBLCLKS  when  initializing  the  window  style  in  the  window 
class  structure  before  calling  Register  Class: 

wndcl ass. style  =  CS_H REDRAW  !  CS.VREDRAW  !  CS_DBLCLKS  ; 

If  you  do  not  include  CS_DBLCLKS  in  the  window  style  and  the  user  clicks  the  left  mouse 
button  twice  in  quick  succession,  your  window  procedure  receives  these  messages: 
WM_LBUTTONDOWN,  WM_LBUTTONUP,  WM_LBUTTONDOWN,  and  WM-LBUT- 
TONUP.  (The  window  procedure  might  also  receive  other  messages  between  these  button 
messages.)  If  you  want  to  implement  your  own  double-click  logic,  you  can  use  the  Win¬ 
dows  function  GetMessageTime  to  obtain  the  relative  times  of  the  WM-LBUTTONDOWN 
messages.  This  function  is  discussed  in  more  detail  in  Chapter  5. 

If  you  include  CS_DBLCLKS  in  your  window  class,  the  window  procedure  receives 
these  messages  for  a  double-click:  WM-LBUTTONDOWN,  WM-LBUTTONUP,  WM- 
_LBUTTONDBLCLK,  and  WM_LBUTTONUP.  The  WM-LBUTTONDBLCLK  message  sim¬ 
ply  replaces  the  second  WM-LBUTTONDOWN  message. 

Double-click  messages  are  much  easier  to  process  if  the  first  click  of  a  double-click 
performs  the  same  action  as  a  single  click.  The  second  click  (the  WM_LBUTTONDBLCLK 
message)  then  does  something  in  addition  to  the  first  click.  For  example,  look  at  how  the 
mouse  works  with  the  file  list  in  the  File  Manager  program.  A  single  click  selects  the  file. 
The  File  Manager  highlights  the  file  with  a  reverse-video  bar.  A  double-click  performs  two 
actions:  The  first  click  selects  the  file,  just  as  a  single  click  does;  the  second  click  (which  is 
a  WM_LBUTTONDBLCLK  message)  directs  the  File  Manager  to  run  the  file.  That’s  fairly 
easy  logic. 

Mouse-handling  logic  could  get  more  complex  if  the  first  click  of  a  double-click  does 
not  perform  the  same  action  as  a  single  click. 
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NONCLIENT-AREA  MOUSE  MESSAGES 

The  10  mouse  messages  discussed  so  far  occur  when  the  mouse  is  moved  or  clicked  within 
the  client  area  of  a  window.  If  the  mouse  is  outside  a  window’s  client  area  but  still  within 
the  window,  Windows  sends  the  window  procedure  a  “nonclient-area”  mouse  message. 
The  nonclient  area  includes  the  caption  bar,  the  menu,  and  window  scroll  bars. 

You  do  not  usually  need  to  process  nonclient-area  mouse  messages.  Instead,  you 
simply  pass  them  on  to  DefWindoivProc  so  Windows  can  perform  system  functions.  In  this 
respect,  the  nonclient-area  mouse  messages  are  similar  to  the  system  keyboard  messages 
WM.SYSKEYDOWN,  WM.SYSKEYUP,  and  WM_SYSCHAR. 

The  nonclient-area  mouse  messages  parallel  almost  exactly  the  client-area  mouse 
messages.  The  messages  include  the  letters  “NC”  to  indicate  “nonclient.”  If  the  mouse  is 
moved  within  a  nonclient  area  of  a  window,  then  the  window  procedure  receives  the  mes¬ 
sage  WM_NCMOUSEMOVE.  The  mouse  buttons  generate  these  messages: 


Button 

Pressed 

Released 

Pressed  (Second  Click) 

Left 

Middle 

Right 

WM-NCLBUTTONDOWN 

WM  -NCMBUTTON  DOWN 

WM -NCRBUTTON  DOWN 

WM-NCLBUTTONUP 

WM-NCMBUTTONUP 

WM-NCRBUTTONUP 

WM -NCLBUTTON  DBLCLK 

WM  -NCMBUTTONDBLCLK 

WM  -NCRBUTTON  DBLCLK 

However,  the  wParam  and  IParam  parameters  for  nonclient-area  mouse  messages 
are  different  from  those  for  client-area  mouse  messages.  The  wParam  parameter  indicates 
the  nonclient  area  where  the  mouse  was  moved  or  clicked.  It  is  set  to  one  of  the  identi¬ 
fiers  beginning  with  HT  that  are  defined  in  WINDOWS. H  (such  as  HTCAPTION  and 
HTSYSMENU). 

The  IParam  variable  contains  an  x-coordinate  in  the  low  word  and  a  ^-coordinate  in 
the  high  word.  However,  these  are  screen  coordinates,  not  client-area  coordinates  as  they 
are  for  client-area  mouse  messages.  For  screen  coordinates,  the  upper  left  corner  of  the  dis¬ 
play  area  has  x  and  y  values  of  0.  Values  of  x  increase  as  you  move  to  the  right,  and  values 
of  y  increase  as  you  move  down.  (See  Figure  4-3.) 

You  can  convert  screen  coordinates  to  client-area  coordinates  and  vice  versa  with 
two  Windows  functions: 

ScreenToCl ient  (hwnd,  IpPoint)  ; 

Cl ientToScreen  (hwnd,  IpPoint)  ; 

The  IpPoint  parameter  is  a  far  (or  long)  pointer  to  a  structure  of  type  POINT.  These  two 
functions  convert  the  values  stored  in  the  structure  without  preserving  the  old  values.  Note 
that  if  a  screen-coordinate  point  is  above  the  window’s  client  area,  then  the  converted 
client-area  jy-coordinate  will  be  negative.  Similarly,  a  screen  coordinate  to  the  left  of  a 
client  area  is  a  negative  x  value  when  expressed  as  a  client-area  coordinate. 
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Screen  coordinates 


Figure  4-3.  Screen  coordinates  and  client-area  coordinates. 


The  Hit-Test  Message 

If  you’ve  been  keeping  count,  you  know  that  we’ve  covered  20  of  the  21  mouse  messages. 
The  last  message  is  WM_NCHITTEST,  which  stands  for  “nonclient  hit  test.”  This  message 
precedes  all  other  client-area  and  nonclient-area  mouse  messages.  The  iParam  parameter 
contains  the  x  and  y  screen  coordinates  of  the  mouse  position.  The  wParam  parameter  is 
not  used. 

Windows  applications  usually  pass  this  message  to  DefWindowProc.  Windows  then 
uses  the  WM_NCHITTEST  message  to  generate  all  other  mouse  messages,  based  on  the 
position  of  the  mouse.  For  nonclient-area  mouse  messages,  the  value  returned  from  Def¬ 
WindowProc  when  processing  WM-NCHITTEST  becomes  the  wParam  parameter  in 
the  mouse  message.  This  value  can  be  any  of  the  wParam  values  that  accompany  the 
nonclient-area  mouse  messages  plus  the  following: 

HTCLIENT  Client  area 

HTNOWHERE  Not  on  any  window 

HTTRANSPARENT  A  window  covered  by  another  window 
HTERROR  Causes  DefWindowProc  to  produce  a  beep 
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If  DefWindowProc  returns  HTCLIENT  after  it  processes  a  WM_NCHITTEST  message, 
then  Windows  converts  the  screen  coordinates  to  client-area  coordinates  and  generates  a 
client-area  mouse  message. 

If  you  remember  how  we  disabled  all  system  keyboard  functions  by  trapping  the 
WM-SYSKEYDOWN  message,  you  may  wonder  if  you  can  do  something  similar  by  trap¬ 
ping  mouse  messages.  Sure.  If  you  include  the  lines: 

case  WM_NCH I TTEST  : 

return  (long)  HTNOWH ERE  ; 

in  your  window  procedure,  you  will  effectively  disable  all  client-area  and  nonclient-area 
mouse  messages  to  your  window.  The  mouse  buttons  will  simply  not  work  while  the 
mouse  is  anywhere  within  your  window,  including  the  system  menu  box  and  size  box. 

Messages  Beget  Messages 

Windows  uses  the  WM_NCHITTEST  message  to  generate  all  other  mouse  messages.  The 
idea  of  messages  giving  birth  to  other  messages  is  common  in  Windows.  Let’s  take  an  ex¬ 
ample.  As  you  know,  if  you  double-click  the  system  menu  box  of  a  Windows  program,  the 
program  will  be  terminated.  The  double-click  generates  a  series  of  WM-NCHITTEST 
messages.  Because  the  mouse  is  positioned  over  the  system  menu  box,  DefWindowProc 
returns  a  value  of  HTSYSMENU  and  Windows  puts  a  WM_NCLBUTTONDBLCLK  message 
in  the  message  queue  with  wParam  equal  to  HTSYSMENU. 

The  window  procedure  usually  passes  that  mouse  message  to  DefWindowProc . 
When  DefWindowProc  receives  the  WM_NCLBUTTONDBLCLK  message  with  wParam 
equal  to  HTSYSMENU,  it  puts  a  WM_SYSCOMMAND  message  with  wParam  equal  to 
SC-CLOSE  in  the  message  queue.  (This  WM-SYSCOMMAND  message  is  also  generated 
when  a  user  selects  Close  from  the  system  menu  box.)  Again,  the  window  procedure 
usually  passes  that  message  to  DefWindowProc.  DefWindowProc  processes  the  message 
by  sending  a  WM -CLOSE  message  to  the  window  procedure. 

If  a  program  wants  to  require  confirmation  from  a  user  before  terminating,  the  win¬ 
dow  procedure  can  trap  WM-CLOSE.  Otherwise,  DefWindowProc  processes  WM-CLOSE 
by  calling  the  DestroyWindow  function.  Among  other  actions,  DestroyWindow  sends  a 
WM -DESTROY  message  to  the  window  procedure.  Normally,  a  window  procedure  pro¬ 
cesses  WM -DESTROY  with  the  code: 

case  WMJESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

The  PostQuitMessage  causes  Windows  to  place  a  WM-QUIT  message  in  the  message 
queue.  This  message  never  reaches  the  window  procedure  because  it  causes  GetMessage 
to  return  0,  which  terminates  the  message  loop  and  the  program. 
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HIT-TESTING  IN  YOUR  PROGRAMS 

Earlier  I  discussed  how  the  File  Manager  responds  to  mouse  clicks  and  double-clicks. 
Obviously,  the  program  must  determine  at  which  file  the  user  is  pointing  with  the  mouse. 
This  is  called  “hit-testing.”  Just  as  DefWindowProc  must  do  some  hit-testing  when  pro¬ 
cessing  WM_NCHITTEST  messages,  very  often  a  window  procedure  must  do  some 
hit-testing  within  the  client  area.  In  general,  hit-testing  involves  calculations  using  the  x- 
and  ^-coordinates  passed  to  your  window  procedure  in  the  IParam  parameter  of  the 
mouse  message. 

A  Hypothetical  Example 

Here’s  an  example.  Your  program  displays  several  columns  of  alphabetically  sorted  files 
similar  to  the  File  Manager  file  windows.  The  file  list  starts  at  the  top  of  the  client  area, 
which  is  cxClient  pixels  wide  and  cyClient  pixels  high;  each  character  is  cyChar  pixels 
high.  The  filenames  are  stored  in  a  sorted  array  of  pointers  to  character  strings  called 
szFileNames. 

Let’s  assume  that  the  columns  are  cxColWidth  pixels  wide.  The  number  of  files  you 
can  fit  in  each  column  is: 

nNumlnCol  =  cyClient  /  cyChar  ; 

You  receive  a  mouse  click  message  with  the  coordinates  cxMouse  and  cyMouse 
derived  from  IParam.  You  can  determine  which  column  of  filenames  the  user  is  pointing 
to  by  using  the  formula: 

nColumn  =  cxMouse  /  cxCol Width  ; 

The  position  of  the  filename  in  relation  to  the  top  of  the  column  is: 

nFromTop  =  cyMouse  /  cyChar  ; 

Now  you  can  calculate  an  index  to  the  szFileNames  array: 
nlndex  =  nColumn  *  nNumlnCol  +  nFromTop  ; 

Obviously,  if  nlndex  exceeds  the  number  of  files  in  the  array,  the  user  is  clicking  on  a  blank 
area  of  the  display. 

In  many  cases,  hit-testing  is  more  complex  than  this  example  suggests.  For  instance, 
it  can  become  very  messy  in  a  word-processing  program  (such  as  WRITE)  that  uses  vari¬ 
able  font  sizes.  When  you  display  something  in  the  client  area,  you  must  determine  the 
coordinates  for  each  item  you  display.  In  hit-testing  calculations,  you  must  go  backward 
from  the  coordinates  to  the  object.  However,  if  the  object  you  display  is  a  string,  then  going 
backward  involves  finding  the  character  position  within  the  string. 
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A  Sample  Program 

The  CHECKER1  program,  shown  in  Figure  4-4,  demonstrates  some  simple  hit-testing.  The 
program  divides  the  client  area  into  a  5-by-5  array  of  25  rectangles.  If  you  click  the  mouse 
on  one  of  the  rectangles,  the  rectangle  is  filled  with  an  X.  If  you  click  there  again,  the  X  is 
removed. 


CHECKER1  .MAK 

# . - 

//  CHECKERl .MAK  make  file 
# . . . - 

checkerl.exe  :  checkerl.obj  checkerl.def 

$(WINLINK)  checkerl,  checkerl,  NUL,  $(WINLIB),  checkerl 
rc  -t  checkerl.exe 

checkerl.obj  :  checkerl. c 
$ ( WI NCC )  checkerl. c 


CHECKER1.C 


/* 


CHECKERl.C  --  Mouse  Hit-Test  Demo  Program  No.  1 
(c)  Charles  Petzold,  1992 


*/ 


//include  <windows.h> 

//define  DIVISIONS  5 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Checkerl"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 


Figure  4-4.  The  CHECKERl  program. 


(continued) 
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wndclass.cbWndExtra  =  0  ; 

wndclass.hlnstance  =  hlnstance  ; 

wndclass.hlcon  =  NULL  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W) 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH) 

wndclass.lpszMenuName  =  NULL  ; 

wndclass.lpszClassName  =  szAppName  ; 


RegisterClass  ( &wndcl ass )  ; 
} 


hwnd  =  CreateWindow  (szAppName,  ”Checkerl  Mouse  Hit-Test  Demo”, 
WS.OVERLAPPEDWINDOW, 

CWJJSEDEFAULT,  COSEDEFAULT, 

CW_USEDEFAULT,  COSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  BOOL  fState[DI VISIONS] [DIVISIONS]  ; 
static  short  cxBlock,  cyBlock  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

RECT  rect  ; 

short  x,  y  ; 

switch  (message) 

{ 

case  WM.SIZE  : 

cxBlock  =  LOWORD  (IParam)  /  DIVISIONS  ; 
cyBlock  =  HIWORD  (IParam)  /  DIVISIONS  ; 
return  0  ; 

case  WM.LBUTTONDOWN  : 

x  =  LOWORD  (IParam)  /  cxBlock  ; 
y  =  HIWORD  (IParam)  /  cyBlock  ; 

if  (x  <  DIVISIONS  &&  y  <  DIVISIONS) 
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fState  [x][y]  A=  1  ; 

rect.left  =  x  *  cxBlock  ; 
rect.top  =  y  *  cyBlock  ; 
rect. right  =  (x  +  1)  *  cxBlock  ; 
rect. bottom  =  (y  +  1)  *  cyBlock  ; 

I n val i dateRect  (hwnd,  &rect,  FALSE)  ; 

} 

else 

MessageBeep  (0)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

for  (x  =  0  ;  x  <  DIVISIONS  ;  x++) 

for  (y  =  0  ;  y  <  DIVISIONS  ;  y++) 

{ 

Rectangle  (hdc,  x  *  cxBlock,  y  *  cyBlock, 

(x  +  1)  *  cxBlock,  (y  +  1)  *  cyBlock)  ; 

if  (fState  [x] [y] ) 

{ 

MoveTo  (hdc,  x  *  cxBlock,  y  *  cyBlock) 

LineTo  (hdc,  (x+1)  *  cxBlock,  (y+1)  *  cyBlock) 

MoveTo  (hdc,  x  *  cxBlock,  (y+1)  *  cyBlock) 

LineTo  (hdc,  (x+1)  *  cxBlock,  y  *  cyBlock) 

} 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


CHECKER  1.DEF 


CHECKERl.DEF  module  definition  file 


NAME  CHECKERl 


(continued) 
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DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


’Mouse  Hit-Test  Demo  Program  No.  1  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


Figure  4-5  shows  the  CHECKER1  display.  All  25  rectangles  have  the  same  width  and 
height.  These  width  and  height  values  are  stored  in  cxBlock  and  cyBlock  and  are  recalcu¬ 
lated  when  the  size  of  the  client  area  changes.  The  WM_LBUTTONDOWN  logic  uses  the 
mouse  coordinates  to  determine  which  rectangle  has  been  clicked.  It  flags  the  current 
state  of  the  rectangle  in  the  array  f  State  and  invalidates  the  rectangle  to  generate  a  WM- 
_PAINT  message.  If  the  width  or  height  of  the  client  area  is  not  evenly  divisible  by  five,  a 
small  strip  of  client  area  at  the  left  or  bottom  will  not  be  covered  by  a  rectangle.  For  error 
processing,  CHECKER1  responds  to  a  mouse  click  in  this  area  by  calling  MessageBeep. 

When  CHECKER1  receives  a  WM_PAINT  message,  it  repaints  the  entire  client  area 
by  drawing  rectangles  using  the  GDI  Rectangle  function.  If  the  /State  value  is  set, 
CHECKERl  draws  two  lines  using  the  MoveTo  and  LineTo  functions.  During  WM_PAINT 


Figure  4-5.  The  CHECKERl  display. 


153 


SECTION  II:  READING  INPUT 


processing,  CHECKER1  does  not  check  the  validity  of  each  rectangular  section  before  re¬ 
painting  it,  but  it  could.  One  method  for  checking  validity  involves  building  a  RECT  struc¬ 
ture  for  each  rectangular  block  within  the  loop  (using  the  same  formulas  as  in  the 
WM_LBUTTONDOWN  logic)  and  checking  whether  it  intersects  the  invalid  rectangle 
(ps. rcPaint)  by  using  the  function  Inter sectRect.  Another  method  is  to  use  PtlnRect  to  de¬ 
termine  if  any  of  the  four  corners  of  the  rectangular  block  are  within  the  invalid  rectangle. 

Emulating  the  Mouse  with  the  Keyboard 

CHECKERl  works  only  if  you  have  a  mouse.  We’ll  be  adding  a  keyboard  interface  to  the 
program  shortly,  as  we  did  for  the  SYSMETS  program  in  Chapter  3.  However,  adding  a  key¬ 
board  interface  to  a  program  that  uses  the  mouse  cursor  for  pointing  purposes  requires  that 
we  also  must  worry  about  displaying  and  moving  the  mouse  cursor. 

Even  if  a  mouse  device  is  not  installed,  Windows  can  still  display  a  mouse  cursor. 
Windows  maintains  a  “display  count”  for  this  cursor.  If  a  mouse  is  installed,  the  display 
count  is  initially  0;  if  not,  the  display  count  is  initially  -1.  The  mouse  cursor  is  displayed 
only  if  the  display  count  is  0  or  positive.  You  can  increment  the  display  count  by  calling: 

ShowCursor  (TRUE)  ; 
and  decrement  it  by  calling: 

ShowCursor  (FALSE)  ; 

You  do  not  need  to  determine  if  a  mouse  is  installed  before  using  ShowCursor.  If  you 
want  to  display  the  mouse  cursor  regardless  of  the  presence  of  the  mouse,  simply  incre¬ 
ment  the  display  count.  After  you  increment  the  display  count  once,  decrementing  it  will 
hide  the  cursor  if  no  mouse  is  installed  but  leave  it  displayed  if  a  mouse  is  present.  The 
display  count  applies  to  all  of  Windows,  so  you  should  ensure  that  you  increment  and 
decrement  the  display  count  an  equal  number  of  times. 

You  may  want  to  use  the  following  simple  logic  in  your  window  procedure: 

WM_S  ETFOCUS  : 

ShowCursor  (TRUE)  ; 
return  0  ; 

WM_KI LLFOCUS  : 

ShowCursor  (FALSE)  ; 
return  0  ; 

A  window  procedure  receives  the  WM_SETFOCUS  message  when  the  window  obtains  the 
keyboard  input  focus  and  WM_KILLFOCUS  when  it  loses  the  input  focus.  These  are  ideal 
times  to  display  and  hide  the  mouse  cursor.  First,  the  WM_SETFOCUS  and  WM_KILL- 
FOCUS  calls  are  balanced — that  is,  the  window  procedure  will  increment  and  decrement 
the  mouse  cursor  display  count  an  equal  number  of  times.  Second,  for  versions  of  Windows 
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installed  without  a  mouse,  using  the  WM_SETFOCUS  and  WM_KILLFOCUS  messages 
causes  the  cursor  to  be  visible  only  when  the  window  has  the  input  focus.  That  is  also  the 
only  time  the  user  can  move  the  cursor  using  the  keyboard  interface  that  you’ll  design. 

Windows  maintains  a  current  mouse  cursor  position  even  if  a  mouse  is  not  installed. 
If  a  mouse  is  not  installed,  and  you  display  the  mouse  cursor,  it  may  appear  in  any  part  of 
the  display  and  will  remain  in  that  position  until  you  explicitly  move  it.  You  can  obtain  the 
cursor  position  by  using: 

GetCursorPos  (IpPoint)  ; 

where  IpPoint  is  a  far  pointer  to  a  POINT  structure.  The  function  fills  in  the  POINT  fields 
with  the  x-  and  ^-coordinates  of  the  mouse.  You  can  set  the  cursor  position  by  using: 

SetCursorPos  (x,  y)  ; 

In  both  cases,  the  jc  and  y  values  are  screen  coordinates,  not  client-area  coordinates.  (This 
should  be  evident  because  the  functions  do  not  require  a  hwnd  parameter.)  As  noted 
earlier,  you  can  convert  screen  coordinates  to  client-area  coordinates  and  vice  versa  by 
using  ScreenToClient  and  ClientToScreen. 

If  you  call  GetCursorPos  while  processing  a  mouse  message  and  convert  to  client- 
area  coordinates,  the  coordinates  may  still  be  slightly  different  from  those  in  iParam  of  the 
mouse  message.  The  coordinates  returned  from  GetCursorPos  indicate  the  current  posi¬ 
tion  of  the  mouse.  The  coordinates  in  IParam  of  a  mouse  message  are  the  coordinates  of 
the  mouse  when  the  message  was  generated. 

You’ll  probably  want  to  write  keyboard  logic  to  move  the  mouse  cursor  with  the  key¬ 
board  arrow  keys  and  simulate  the  mouse  button  with  the  Spacebar  or  Enter  key.  What  you 
don't  want  to  do  is  move  the  mouse  cursor  one  pixel  per  keystroke.  That  forces  a  user  to 
hold  down  an  arrow  key  for  more  than  a  minute  to  move  the  mouse  cursor  from  one  side  of 
the  display  to  the  other. 

If  you  need  to  implement  a  keyboard  interface  to  the  mouse  cursor  but  still  maintain 
the  ability  to  position  the  cursor  at  precise  pixel  locations,  take  a  look  at  Windows’  PAINT¬ 
BRUSH  program.  When  you  hold  down  an  arrow  key,  the  mouse  cursor  starts  moving 
slowly  but  then  speeds  up.  You’ll  recall  that  the  IParam  parameter  in  WM_KEYDOWN 
messages  indicates  if  the  keystroke  messages  are  the  result  of  typematic  action.  This  is  an 
excellent  application  of  that  information. 

Adding  a  Keyboard  Interface  to  CHECKER 

The  CHECKER2  program,  shown  in  Figure  4-6  on  the  following  page,  is  the  same  as 
CHECKER1  except  that  it  includes  a  keyboard  interface.  You  can  use  the  Left,  Right,  Up, 
and  Down  arrow  keys  to  move  the  cursor  among  the  25  rectangles.  The  Home  key  sends 
the  cursor  to  the  upper  left  rectangle;  the  End  key  drops  it  down  to  the  lower  right  rect¬ 
angle.  Both  the  Spacebar  and  Enter  keys  toggle  the  X  mark. 
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CHECKER2.MAK 

♦ 

♦  CHECKER2.MAK  make  file 

♦ 

checker2.exe  :  checker2.obj  checker2.def 

$(WINLINK)  checker2,  checked,  NUL,  $(WINLIB),  checker2 
rc  -t  checker2.exe 

checker2.obj  :  checker2.c 
$(WINCC)  checker2.c 


CHECKER2.C 


/* . - . 

CHECKER2.C  --  Mouse  Hit-Test  Demo  Program  No.  2 
(c)  Charles  Petzold,  1992 

.  . */ 


#i nclude  <windows.h> 

♦define  DIVISIONS  5 

♦define  min(a.b)  (((a)  <  (b))  ?  (a)  :  (b) ) 
♦define  max(a,b)  (((a)  >  (b) )  ?  (a)  :  (b)) 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT.  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Checker2"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 

Figure  4-6.  The  CHECKER2 program. 


=  CS.HREDRAW  !  CS.VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL,  IDC.ARR0W) 


(continued) 
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wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
wndclass.lpszMenuName  =  NULL  ; 
wndclass.lpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Checker2  Mouse  Hit-Test  Demo", 
WS_OVERLAPPEDWINDOW, 

CW.USEDEFAULT,  CW__USEDE FAULT, 

CW.USEDEFAULT,  CWJJSEDEFAULT, 

NULL.  NULL,  hlnstance.  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL.  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  ^export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  BOOL  fStateCDI VISIONS] [DIVISIONS]  ; 
static  short  cxBlock,  cyBlock  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

POINT  point  ; 

RECT  rect  ; 

short  x.  y  ; 

switch  (message) 

{ 

case  WM.SIZE  : 

cxBlock  =  LOWORD  (IParam)  /  DIVISIONS  ; 
cyBlock  =  HIWORD  (IParam)  /  DIVISIONS  ; 
return  0  ; 

case  WM_SETFOCUS  : 

ShowCursor  (TRUE)  ; 
return  0  ; 

case  WMJ<ILLFOCUS  : 

ShowCursor  (FALSE)  ; 
return  0  ; 


(continued) 
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case  WM.KEYDOWN  : 

GetCursorPos  (&point)  ; 

ScreenToCl ient  (hwnd,  &point)  ; 

x  =  max  (0,  min  (DIVISIONS  -  1,  point. x  /  cxBlock))  ; 
y  =  max  (0.  min  (DIVISIONS  -  1.  point. y  /  cyBlock))  ; 

switch  (wParam) 

{ 

case  VK_UP  : 
y  --  ; 
break  ; 

case  VK_D0WN  : 
y  ++  ; 
break  ; 

case  VK_LEFT  : 
x  --  ; 
break  ; 

case  VK_RIGHT  : 
x  ++  ; 
break  ; 

case  VK_H0ME  : 
x  =  y  =  0  ; 
break  ; 

case  VK_END  : 

x  =  y  =  DIVISIONS  -  1  ; 
break  ; 

case  VK_RETURN  : 
case  VK_SPACE  : 

SendMessage  (hwnd,  WM_LBUTT0ND0WN,  MKJ-BUTTON, 
MAKELONG  (x  *  cxBlock,  y  *  cyBlock))  ; 

break  ; 

} 

x  =  (x  +  DIVISIONS)  %  DIVISIONS  ; 
y  =  (y  +  DIVISIONS)  %  DIVISIONS  ; 

point. x  =  x  *  cxBlock  +  cxBlock  /  2  ; 
point. y  =  y  *  cyBlock  +  cyBlock  /  2  ; 

ClientToScreen  (hwnd,  &point)  ; 

SetCursorPos  (point. x,  point. y)  ; 
return  0  ; 
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case  WM_LBUTT0ND0WN  : 

x  =  LOWORD  (lParam)  /  cxBlock  ; 
y  =  H I WORD  (lParam)  /  cyBlock  ; 

if  (x  <  DIVISIONS  &&  y  <  DIVISIONS) 

{ 

fState  [x][y]  A=  1  ; 

rect.left  =  x  *  cxBlock  ; 
rect.top  =  y  *  cyBlock  ; 
rect. right  =  (x  +  1)  *  cxBlock  ; 
rect. bottom  =  (y  +  1)  *  cyBlock  ; 

InvalidateRect  ( hwnd ,  &rect,  FALSE)  ; 

} 

else 

MessageBeep  (0)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

for  (x  =  0  ;  x  <  DIVISIONS  ;  x++) 

for  (y  =  0  ;  y  <  DIVISIONS  ;  y++) 

{ 

Rectangle  (hdc,  x  *  cxBlock,  y  *  cyBlock, 

(x  +  1)  *  cxBlock,  (y  +  1)  *  cyBlock)  ; 

if  (fState  [x] [y] ) 

{ 

MoveTo  (hdc,  x  *  cxBlock,  y  *  cyBlock) 

LineTo  (hdc,  (x+1)  *  cxBlock,  (y+1)  *  cyBlock) 

MoveTo  (hdc,  x  *  cxBlock,  (y+1)  *  cyBlock) 

LineTo  (hdc,  (x+1)  *  cxBlock,  y  *  cyBlock) 

} 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  lParam)  ; 
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CHECKER2.DEF 


CHECKER2 . DEF  module  definition  file 


NAME  CHECKER2 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Mouse  Hit-Test  Demo  Program  No.  2  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


The  WM_KEYDOWN  logic  in  CHECKER2  determines  the  position  of  the  cursor  ( Get - 
CursorPos),  converts  the  screen  coordinates  to  client-area  coordinates  ( ScreenToClient ), 
and  divides  the  coordinates  by  the  width  and  height  of  the  rectangular  block.  This  pro¬ 
duces  x  and  y  values  that  indicate  the  position  of  the  rectangle  in  the  5-by-5  array.  The 
mouse  cursor  may  or  may  not  be  in  the  client  area  when  a  key  is  pressed,  so  x  and  y  must 
be  passed  through  the  min  and  max  macros  to  ensure  that  they  range  from  0  through  4. 

For  arrow  keys,  CHECKER2  increments  or  decrements  x  and  y  appropriately.  If 
the  key  is  the  Enter  key  (VK_RETURN)  or  Spacebar  (VK.SPACE),  CHECKER2  uses 
SendMessage  to  send  a  WM_LBUTTONDOWN  message  to  itself.  This  technique  is  similar 
to  the  method  used  in  the  SYSMETS  program  in  Chapter  3  to  add  a  keyboard  interface  to 
the  window  scroll  bar.  The  WM-KEYDOWN  logic  finishes  by  calculating  client-area  coor¬ 
dinates  that  point  to  the  center  of  the  rectangle,  converting  to  screen  coordinates  ( Client - 
ToScreen ),  and  setting  the  cursor  position  ( SetCursorPos ). 

Using  Child  Windows  for  Hit-Testing 

Some  programs,  like  the  Windows  PAINTBRUSH  program,  divide  the  client  area  into  sev¬ 
eral  smaller  logical  areas.  The  PAINTBRUSH  program,  shown  in  Figure  4-7,  has  an  area  at 
the  left  for  its  icon-based  menu  and  an  area  at  the  bottom  for  the  color  menu.  PAINT¬ 
BRUSH,  when  hit-testing  on  these  two  menus,  must  take  into  account  the  location  of  the 
menu  within  the  client  area  before  determining  the  menu  item  being  selected  by  the  user. 

Or  maybe  not.  In  reality,  PAINTBRUSH  simplifies  the  menu  drawing  and  hit-testing 
through  the  use  of  “child  windows.”  The  child  windows  divide  the  entire  client  area  into 
several  smaller  rectangular  regions.  Each  child  window  has  its  own  window  handle,  win¬ 
dow  procedure,  and  client  area.  Each  window  procedure  receives  mouse  messages  that 
apply  only  to  its  child  window.  The  iParam  parameter  in  the  mouse  message  contains 
coordinates  relative  to  the  upper  left  corner  of  the  client  area  of  the  child  window,  not  of 
the  parent  window. 
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Paintbrush  -  CHESS.BMP_ QO\ 


File  Edit  View  Jext  Pick  Options  Help 


Figure  4-7.  The  Windows  PAINTBRUSH  program. 

Child  windows  used  in  this  way  can  help  you  structure  and  modularize  your  pro¬ 
grams.  If  the  child  windows  use  different  window  classes,  each  child  window  can  have  its 
own  window  procedure.  The  different  window  classes  can  also  define  different  back¬ 
ground  colors  and  different  default  cursors.  In  Chapter  6,  we’ll  look  at  “child  window 
controls” — predefined  child  windows  that  take  the  form  of  scroll  bars,  buttons,  and  edit 
boxes.  Right  now,  let’s  see  how  we  can  use  child  windows  in  the  CHECKER  program. 

Child  Windows  in  CHECKER 

Figure  4-8  shows  CHECKER3.  This  version  of  the  program  creates  25  child  windows  to 
process  mouse  clicks.  It  does  not  have  a  keyboard  interface,  but  one  could  easily  be  added. 

CHECKER3  has  two  window  procedures  called  WndProc  and  ChildWndProc . 
WndProc  is  still  the  window  procedure  for  the  main  (or  parent)  window.  ChildWndProc 
is  the  window  procedure  for  the  25  child  windows.  Both  window  procedures  must  be 
defined  as  FAR  PASCAL  -export  functions. 

Because  the  window  procedure  is  defined  by  the  window  class  structure  that  you 
register  with  Windows  by  using  the  Register  Class  call,  the  two  window  procedures 
in  CHECKER3-C  require  two  window  classes.  The  first  window  class  is  for  the  main 
window  and  has  the  name  “Checker3”.  The  second  window  class  is  given  the  name 
“Checker3-Child”. 
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Most  of  the  fields  of  the  wndclass  structure  variable  are  simply  reused  when 
“Checker3-Child”  is  registered  in  WinMain.  The  IpszClassName  field  is  set  to 
“Checker3-Child”  (the  name  of  the  class).  The  IpfnWndProc  field  is  set  to  ChildWndProc , 
the  window  procedure  for  this  window  class,  and  the  hlcon  field  is  set  to  NULL  be¬ 
cause  icons  are  not  used  with  child  windows.  For  the  “Checker3-Child”  window  class,  the 
cbWndExtra  field  in  the  wndclass  structure  variable  is  set  to  2  bytes,  or  more  precisely, 
sizeofi WORD).  This  field  tells  Windows  to  reserve  2  bytes  of  extra  space  in  a  structure  that 
Windows  maintains  for  each  window  based  on  this  window  class.  You  can  use  this  space  to 
store  information  that  may  be  different  for  each  window. 

CHECKER3.MAK 

# 

#  CHECKER3.MAK  make  file 

#  . 

checker3.exe  :  checker3.obj  checker3.def 

$(WINLINK)  checked  checked,  NUL,  $(WINLIB),  checked 
rc  -t  checker3.exe 

checker3.obj  :  checker3.c 
$ ( W I NCC )  checked. c 


CHECKER3.C 


/* . 

CHECKER3.C  --  Mouse  Hit-Test  Demo  Program  No.  3 
(c)  Charles  Petzold,  1992 

. */ 


♦include  <windows.h> 
♦define  DIVISIONS  5 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

long  FAR  PASCAL  .export  ChildWndProc  (HWND,  UINT,  UINT,  LONG)  ; 

char  szChi 1 dCl ass[]  =  "Checker3_Child"  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 


{ 


Figure  4-8.  The  CHECKER3  program. 


(continued) 
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static  char  szAppName[]  =  "Checker3"  ; 
HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbrBackg round 
wndclass. IpszMenuName 
wndclass. IpszClassName 


CS.HREDRAW  !  CSJ/REDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  I D I_APP LI CATI ON )  ; 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITE_BRUSH)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 


wndclass. lpfnWndProc  =  Chi  1 dWndProc  ; 

wndclass. cbWndExtra  =  sizeof  (WORD)  ; 

wndclass. hlcon  =  NULL  ; 

wndclass. IpszClassName  =  szChildClass  ; 

RegisterClass  (&wndclass)  ; 

} 


hwnd  =  CreateWindow  (szAppName,  ”Checker3  Mouse  Hit-Test  Demo", 
WS_0V  ERLAPPEDWI NDOW , 

CW_USEDEFAULT,  CW.USEDEFAULT, 

CWJJSEDEFAULT,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  ^export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HWND  hwndChild  [DIVISIONS]  [DIVISIONS]  ; 
short  cxBlock,  cyBlock,  x,  y  ; 
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switch  (message) 

{ 

case  WM.CREATE  : 

for  (x  =  0  ;  x  <  DIVISIONS  ;  x++) 

for  (y  =  0  ;  y  <  DIVISIONS  ;  y++) 

{ 

hwndChild  [x][y]  =  CreateWindow  (szChildClass,  NULL, 
WS_CH I LDW I NDOW  !  WS.VISIBLE, 

0,  0,  0,  0 » 
hwnd,  y  <<  8  !  x, 

GetWindowWord  (hwnd,  GWW_H I NSTANCE ) ,  NULL)  ; 

} 

return  0  ; 
case  WM.SIZE  : 

cxBlock  =  LOWORD  (IParam)  /  DIVISIONS  ; 
cyBlock  =  HIWORD  (IParam)  /  DIVISIONS  ; 

for  (x  =  0  ;  x  <  DIVISIONS  ;  x++) 

for  (y  =  0  ;  y  <  DIVISIONS  ;  y++) 

MoveWindow  (hwndChild  [x][y], 
x  *  cxBlock,  y  *  cyBlock, 
cxBlock,  cyBlock,  TRUE)  ; 

return  0  ; 

case  WM_LBUTT0ND0WN  : 

MessageBeep  (0)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

long  FAR  PASCAL  _export  Chi  1 dWndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

RECT  rect  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

SetWindowWord  (hwnd,  0,  0)  ;  //  on/off  flag 

return  0  ; 


(continued) 
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case  WMJ_BUTT0ND0WN  : 

SetWindowWord  (hwnd,  0,  1  A  GetWindowWord  (hwnd,  0))  ; 
Inval idateRect  (hwnd,  NULL,  FALSE)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

GetClientRect  (hwnd,  &rect)  ; 

Rectangle  (hdc,  0,  0,  rect. right,  rect. bottom)  ; 

if  (GetWindowWord  (hwnd,  0)) 

{ 

MoveTo  (hdc,  0,  0)  ; 

LineTo  (hdc,  rect. right,  rect. bottom)  ; 

MoveTo  (hdc,  0,  rect. bottom)  ; 

LineTo  (hdc,  rect. right,  0)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


CHECKER3.DEF 


CHECKER3.DEF  module  definition  file 


NAME  CHECKER3 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Mouse  Hit-Test  Demo  Program  No.  3  (c)  Charles  Petzold,  1992’ 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


The  CreateWindow  call  in  WinMain  creates  the  main  window  based  on  the 
“Checker3”  class.  This  is  normal.  However,  when  WndProc  receives  a  WM_CREATE 
message,  it  calls  CreateWindow  25  times  to  create  25  child  windows  based  on  the 
“Checker3-Child”  window  class.  The  table  on  the  following  page  provides  a  comparison 
of  the  parameters  to  the  CreateWindow  call  in  WinMain  that  creates  the  main  window  and 
the  CreateWindow  call  in  WndProc  that  creates  the  25  child  windows. 
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Parameter 

Main  Window 

Child  Window 

window  class 

“Checker3” 

“Checker3-Child” 

window  caption 

“Checker3. . .  ” 

NULL 

window  style 

WS-OVERLAPPEDWINDOW 

WS-CHILDWINDOW  !  WS-VISIBLE 

horizontal  position 

CW.USEDEFAULT 

0 

vertical  position 

CW-USEDEFAULT 

0 

width 

CW-USEDEFAULT 

0 

height 

CW_USEDEFAULT 

0 

parent  window  handle 

NULL 

hwnd 

menu  handle/child  ID 

NULL 

y«  8  !  x 

instance  handle 

hlnstance 

GetWindowWord  ( hwnd , 

GWW-H  INSTANCE) 

extra  parameters 

NULL 

NULL 

Normally  the  position,  width,  and  height  parameters  are  required  for  child  windows, 
but  in  CHECKER3  the  child  windows  are  positioned  and  resized  later  in  WndProc.  The 
parent  window  handle  is  NULL  for  the  main  window  because  it  is  the  parent.  The  parent 
window  handle  is  required  when  using  the  CreateWindow  call  to  create  a  child  window. 

The  main  window  doesn’t  have  a  menu,  so  that  parameter  is  NULL.  For  child  win¬ 
dows,  the  same  parameter  position  is  called  a  “child  ID.”  This  is  a  number  that  uniquely 
identifies  the  child  window.  The  child  ID  becomes  much  more  important  when  working 
with  child  window  controls  because  messages  to  the  parent  window  are  identified  by  this 
child  ID.  For  CHECKER3,  I’ve  used  the  child  ID  to  identify  the  position  that  each  child  win¬ 
dow  occupies  in  the  5-by-5  array  within  the  main  window. 

The  instance  handle  is  hlnstance  in  both  cases.  When  the  child  window  is  created, 
the  hlnstance  value  is  extracted  using  the  function  GetWindowWord  from  the  structure 
that  Windows  maintains  for  the  window.  (Rather  than  use  GetWindowWord ,  I  could  have 
saved  the  value  of  hlnstance  in  a  global  variable  and  used  it  directly.) 

Each  child  window  has  a  different  window  handle  that  is  stored  in  the  hwndChild  ar¬ 
ray.  When  WndProc  receives  a  WM_SIZE  message,  it  calls  MoveWindow  for  each  of  the  25 
child  windows.  The  parameters  indicate  the  upper  left  corner  of  the  child  window  relative 
to  the  parent  window  client-area  coordinates,  the  width  and  height  of  the  child  window, 
and  whether  the  child  window  needs  repainting. 

Now  let’s  take  a  look  at  ChildWndProc .  This  window  procedure  processes  messages 
for  all  25  child  windows.  The  hwnd  parameter  to  ChildWndProc  is  the  handle  to  the  child 
window  receiving  the  message.  When  ChildWndProc  processes  a  WM -CREATE  message 
(which  will  happen  25  times  because  there  are  25  child  windows),  it  uses  SetWindowWord 
to  store  a  0  in  the  extra  area  reserved  within  the  window  structure.  (Recall  that  we 
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reserved  this  space  by  using  the  cbWndExtra  field  when  defining  the  window  class  struc¬ 
ture.)  ChildWndProc  uses  this  value  to  store  the  current  state  (X  or  no  X)  of  the  rectangle. 
When  the  child  window  is  clicked,  the  WM_LBUTTONDOWN  logic  simply  flips  the  value 
of  this  word  (from  0  to  1  or  from  1  to  0)  and  invalidates  the  entire  child  window  client  area. 
This  area  is  the  single  rectangle  being  clicked.  The  WM_PAINT  processing  is  trivial  be¬ 
cause  the  size  of  the  rectangle  it  draws  is  the  same  size  as  the  client  window. 

Because  the  C  source  code  file  and  the  .EXE  file  of  CHECKER3  are  larger  than  those 
for  CHECKER1  (to  say  nothing  of  my  explanation  of  the  programs),  I  will  not  try  to  con¬ 
vince  you  that  CHECKER3  is  “simpler”  than  CHECKER1.  But  note  that  we  no  longer  have  to 
do  any  mouse  hit-testing!  If  a  child  window  in  CHECKER3  gets  a  WM_LBUTTONDOWN 
message,  the  window  has  been  hit,  and  that’s  all  it  needs  to  know. 

If  you  want  to  add  a  keyboard  interface  to  CHECKER3,  keep  in  mind  that  the  main 
window  still  gets  keyboard  messages  because  it  has  the  input  focus.  Well  explore  child 
windows  more  in  Chapter  6. 

CAPTURING  THE  MOUSE 

A  window  procedure  normally  receives  mouse  messages  only  when  the  mouse  cursor  is 
positioned  over  the  client  or  nonclient  area  of  the  window.  A  program  that  needs  to 
receive  mouse  messages  when  the  mouse  is  outside  the  window  can  “capture”  the  mouse. 
Capturing  the  mouse  is  easier  than  baiting  a  mousetrap.  You  need  only  call: 

SetCapture  (hwnd)  ; 

After  this  function  call,  Windows  sends  all  mouse  messages  to  the  window  procedure  for 
the  window  whose  handle  is  hwnd.  The  mouse  messages  are  always  client-area  messages, 
even  when  the  mouse  is  in  a  nonclient  area  of  the  window.  The  iParam  parameter  still 
indicates  the  position  of  the  mouse  in  client-area  coordinates.  These  x-  and  ^-coordinates, 
however,  can  be  negative  if  the  mouse  is  to  the  left  of  or  above  the  client  area. 

During  the  time  the  mouse  is  captured,  system  keyboard  functions  are  also  disabled. 
When  you  want  to  release  the  mouse,  call: 

ReleaseCapture  ()  ; 

This  returns  processing  to  normal. 

The  BLOWUP1  Program 

The  BLOWUP1  program,  shown  in  Figure  4-9  on  the  following  page,  uses  SetCapture  and 
ReleaseCapture  and  a  few  other  interesting  techniques.  The  program  lets  you  use  the 
mouse  to  block  out  any  rectangular  area  of  the  screen.  BLOWUP1  then  copies  the  contents 
of  that  rectangular  area  into  its  own  client  area,  stretching  or  compressing  the  image  as 
appropriate.  (See  Figure  4-10  on  page  171.) 
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BLOWUP1.MAK 

# 

#  BL0WUP1.MAK  make  file 

#  . 

blowupl.exe  :  blowupl.obj  blowupl.def 

$(WINLINK)  blowupl,  blowupl,  NUL,  $(WINLIB).  blowupl 
re  -t  blowupl.exe 

blowupl.obj  :  blowupl. c 
$(WINCC)  blowupl. c 


BLOWUP1.C 

/* . 

BL0WUP1.C  --  Screen  Capture  Mouse  Demo  Program 
(c)  Charles  Petzold,  1992 

.  . */ 


#include  <windows.h> 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "BlowUpl"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. 1 pfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbrBackg round 
wndclass. 1 pszMenuName 
wndclass. 1 pszCl assName 


CS_H REDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  I DI_APPLI CATION )  ; 
LoadCursor  (NULL,  IDC.ARR0W)  ; 
GetStockObject  (WHIT E_B RUSH)  ; 

NULL  ; 
szAppName  ; 


Figure  4-9.  The  BLOWUP  1  program. 
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RegisterClass  ( &wndcl ass )  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Blow-Up  Mouse  Demo", 
WS.OVERLAPPEDWINDOW, 

CW.USEDEFAULT,  CW.USEDEFAULT, 

CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  InvertBlock  (HWND  hwnd,  POINT  ptBeg,  POINT  pt End ) 

{ 

HDC  hdc  ; 

hdc  =  CreateDC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 

ClientToScreen  (hwnd,  &ptBeg)  ; 

ClientToScreen  (hwnd,  &ptEnd)  ; 

PatBlt  (hdc,  ptBeg. x,  ptBeg. y,  ptEnd.x  -  ptBeg. x,  ptEnd.y  -  ptBeg. y, 
DSTINVERT)  ; 

DeleteDC  (hdc)  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  BOOL  fCapturing,  fBlocking  ; 
static  POINT  ptBeg,  ptEnd  ; 

HDC  hdc  ; 

RECT  rect  ; 

switch  (message) 

{ 

case  WM.LBUTTONDOWN  : 
if  ( ! f Capturi ng ) 

{ 

fCapturing  =  TRUE  ; 

SetCapture  (hwnd)  ; 

SetCursor  (LoadCursor  (NULL,  IDC.CROSS))  ; 

} 

else  if  ( IfBlocking) 


(continued) 
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{ 

fBlocking  =  TRUE  ; 

ptBeg  =  MAKEPOINT  (IParam)  ; 

} 

return  0  ; 

case  WM_M0US EMO V E  : 
if  (fBlocking) 

{ 

ptEnd  =  MAKEPOINT  (IParam)  ; 

InvertBlock  (hwnd,  ptBeg,  ptEnd)  ; 

InvertBlock  (hwnd,  ptBeg,  ptEnd)  ; 

} 

return  0  ; 

case  WM.LBUTTONUP  : 
if  (fBlocking) 

{ 

fCapturing  =  fBlocking  =  FALSE  ; 
ptEnd  =  MAKEPOINT  (IParam)  ; 

SetCursor  (LoadCursor  (NULL,  IDC.WAIT))  ; 

hdc  =  GetDC  (hwnd)  ; 

GetClientRect  (hwnd,  &rect)  ; 

StretchBlt  (hdc,  0,  0,  rect. right,  rect. bottom, 
hdc,  ptBeg. x,  ptBeg. y, 
ptEnd. x  -  ptBeg. x,  ptEnd. y  -  ptBeg. y, 
SRCCOPY)  ; 

ReleaseDC  (hwnd,  hdc)  ; 

SetCursor  (LoadCursor  (NULL,  IDC_ARR0W) )  ; 
ReleaseCapture  ()  ; 

} 

return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


BLOWUP1.DEF 


BL0WUP1 . DEF  module  definition  file 


NAME  BL0WUP1 
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DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Blow-Up  Mouse  Demo  Program  (c)  Charles  Petzold,  1992’ 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


File  Manager 


File  Manager  Program 
Manager 


Figure  4-10.  The  BLOWUP1  client  area. 

The  job  of  stretching  and  compressing  bitmapped  images  may  seem  complex,  but  it’s 
simplified  for  us  by  a  Windows  GDI  function  called  StretchBlt.  (The  abbreviation  Bit  is 
pronounced  “blit.”  The  function  is  related  to  the  Windows  BitBlt  function,  which  stands 
for  “bit-block  transfer.”  These  functions  are  discussed  in  more  detail  in  Chapter  13.) 

Here’s  how  to  use  BLOWUP1: 

1.  Click  the  mouse  in  BLOWUP l’s  client  area.  The  mouse  cursor  changes  to 
a  cross  hair. 

2.  Position  the  mouse  cursor  over  the  upper  left  corner  of  the  screen  area 
you  want  to  transfer. 

3.  Press  the  mouse  button,  drag  the  mouse  to  the  lower  right  corner,  and 
release  the  mouse  button.  The  mouse  cursor  changes  to  an  hourglass. 
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4.  In  a  few  seconds  (or  perhaps  a  little  longer),  the  area  that  you  blocked 
out  is  copied  to  BLOWUPl’s  client  area,  compressed  or  expanded 
appropriately. 

If  you  block  out  a  rectangle  by  moving  from  the  upper  right  corner  to  the  lower  left 
corner,  BLOWUP1  displays  a  mirror  image.  If  you  move  from  the  lower  left  to  the  upper 
right,  BLOWUP1  displays  an  upside-down  image.  And  if  you  move  from  the  lower  right  to 
the  upper  left,  the  program  combines  the  two  effects. 

BLOWUP1  doesn’t  retain  the  captured  image  and  doesn’t  process  the  WM_PAINT 
message.  If  you  change  the  size  of  the  window,  the  window  will  be  erased. 

Changing  the  Mouse  Cursor  Shape 

BLOWUPl  uses  the  SetCursor  calls  to  change  the  cursor  shape  from  an  arrow  to  a  cross 
hair,  then  to  an  hourglass,  and  back  to  an  arrow.  All  these  are  stock  cursors  available  in 
Windows.  You  obtain  the  handle  to  the  cursor  using  the  LoadCursor  function.  In  Chapter  8 
we’ll  use  LoadCursor  to  display  customized  mouse  cursors. 

Many  applications  display  an  hourglass  cursor  (defined  in  WINDOWS.H  as  IDC- 
_WAIT)  while  doing  processing  that  may  take  some  time  to  complete.  This  is  fairly  simple 
to  implement.  You  can  save  the  handle  to  the  original  cursor  by  storing  the  return  value 
from  SetCursor  and  using  it  to  reset  the  cursor  later.  First  you’ll  need  a  variable  of  type 
HCURSOR  (defined  in  WINDOWS.H  as  a  HANDLE,  or  16-bit  WORD)  to  store  that  value: 

HCURSOR  hCursor  ; 

Right  before  you  start  the  lengthy  processing,  use  the  following  two  lines: 

hCursor  =  SetCursor  (LoadCursor  (NULL,  I DC_WAI T ) )  ; 

ShowCursor  (TRUE)  ; 

After  you’ve  finished  the  work,  call: 

ShowCursor  (FALSE)  ; 

SetCursor  (hCursor)  ; 

The  two  ShowCursor  calls  display  and  then  hide  the  hourglass  cursor  if  a  mouse  is  not 
actually  present. 

Normally,  Windows  changes  the  mouse  cursor  to  the  cursor  included  in  the  window 
class  structure  whenever  the  window  procedure  receives  a  WM_MOUSEMOVE  message. 
If  you  use  SetCursor  to  change  the  mouse  cursor  and  then  exit  the  window  procedure,  the 
mouse  cursor  will  be  restored  to  the  cursor  in  the  window  class  structure  the  next  time  the 
mouse  is  moved.  This  does  not  happen  in  BLOWUPl  because  the  mouse  is  captured  during 
the  time  the  cross-hair  cursor  (IDC_CROSS)  is  displayed.  Windows  will  not  change  the 
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cursor  to  the  window  class  cursor  when  the  mouse  is  captured.  Also,  if  you  need  to  display 
an  hourglass  cursor  when  doing  some  lengthy  work  (as  BLOWUP1  does  when  it  calls 
StretchBIt),  you  don’t  have  to  worry  about  the  problem  because  you’re  not  receiving  any 
other  messages  during  that  time. 

But  if  you  want  to  use  different  mouse  cursors  for  other  purposes,  you  should  define  a 
NULL  cursor  handle  in  your  window  class: 

wndclass.hCursor  =  NULL  ; 

In  your  window  function,  you  then  call  SetCursor  for  each  WM_MOUSEMOVE  message. 
The  SetCursor  call  is  fast  if  the  mouse  cursor  is  not  being  changed. 

The  StretchBIt  Call 

BLOWUPl  calls  the  StretchBIt  function  during  processing  of  the  WM_LBUTTONUP 
message  to  transfer  the  blocked-out  image  to  BLOWUPl’s  client  area: 

StretchBIt  (hdc,  0,  0,  rect. right,  rect. bottom, 
hdc,  ptBeg.x,  ptBeg.y, 
ptEnd.x  -  ptBeg.x,  ptEnd.y  -  ptBeg.y, 

SRCCOPY )  ; 

This  function  is  discussed  in  more  detail  in  Chapter  13,  but  let’s  take  a  quick  look  at  it  here. 

StretchBIt  transfers  a  bitmapped  image  from  a  source  to  a  destination.  The  first  five 
parameters  are  for  the  destination  of  the  image,  defining  the  device  context  handle,  the 
x-  and  jp-coordinates  of  the  upper  left  corner,  and  the  width  and  height.  The  next  five  pa¬ 
rameters  give  the  same  information  for  the  source  of  the  image.  The  last  parameter  is  the 
operation,  which  in  this  case  is  a  simple  copy  from  source  to  destination. 

The  source  of  the  image  involves  two  POINT  structures  named  ptBeg  (beginning  of 
the  block)  and  ptEnd  (end  of  the  block).  These  two  points  have  negative  coordinate  values 
if  you  block  out  an  image  to  the  left  of  or  above  the  client  area.  StretchBIt  can  read  a  bit¬ 
mapped  image  that  falls  outside  the  client  area,  but  like  all  GDI  functions  it  cannot  write 
outside  the  client  area. 

Drawing  the  Capture  Block 

But  wait.  When  you  use  BLOWUPl  to  block  out  an  image  outside  its  client  area,  the  pro¬ 
gram  briefly  displays  the  image  in  reverse  video  and  then  restores  it  to  normal.  BLOWUPl 
is  apparently  writing  outside  its  client  area.  Can  that  be  so? 

It  certainly  can.  This  little  trick  is  carried  off  in  BLOWUPl’s  InvertBlock  function. 
Rather  than  obtain  a  device  context  handle  from  GetDC,  InvertBlock  uses  CreateDC : 

hdc  =  CreateDC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 

This  returns  a  device  context  handle  for  the  entire  display.  Using  this  device  context 
handle,  you  can  write  outside  your  client  area. 
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InvertBlock  uses  the  GDI  PatBlt  function  (a  “pattern  bit-block  transfer”)  to  invert 
the  blocked-out  image.  BLOWUP1  calls  InvertBlock  twice  in  succession.  When  called  the 
second  time,  the  block  is  restored  to  normal.  This  means  that  you  can  see  the  block  briefly 
only  when  you  move  the  mouse  cursor. 

Why  do  it  like  this?  BLOWUP1  doesn’t  leave  the  block  in  an  inverted  state  because 
other  Windows  programs  can  receive  messages  between  BLOWUPl’s  WM_MOUSEMOVE 
messages.  (For  instance,  the  Windows  CLOCK  gets  WM -TIMER  messages  every  second.)  If 
BLOWUP1  left  the  block  inverted  when  it  exited  its  window  function,  then  the  program 
with  the  altered  client  area  could  write  over  the  inverted  block.  When  BLOWUP1  then 
reinverted  the  block — that  is,  returned  it  to  normal — the  result  would  start  looking  like 
a  mess.  Keep  considerations  like  this  in  mind  when  you  start  working  with  powerful 
functions  like  CreateDC.  Windows  gives  you  the  power  to  do  almost  anything,  but  your 
programs  must  share  resources  such  as  the  display  with  other  programs.  Try  to  exercise 
a  little  restraint. 
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The  Windows  timer  is  an  input  device  that  periodically  notifies  an  application  when  a 
specified  interval  of  time  has  elapsed.  Your  program  tells  Windows  the  interval,  in  effect 
saying,  for  example,  “Give  me  a  nudge  every  10  seconds.”  Windows  then  sends  your  pro¬ 
gram  recurrent  WM_TIMER  messages  to  signal  the  intervals. 

At  first,  the  Windows  timer  may  seem  a  less  important  input  device  than  the  keyboard 
or  mouse,  and  certainly  it  is  for  many  applications.  But  the  timer  is  more  useful  than  you 
may  think,  and  not  only  for  programs  (like  the  Windows  CLOCK)  that  keep  time.  The 
CALENDAR,  CONTROL,  PANEL,  SPOOLER,  TERMINAL,  and  WRITE  programs  supplied 
with  Windows  also  use  the  timer.  Here  are  some  uses  for  the  Windows  timer,  some  obvious 
and  some  perhaps  not  so  obvious: 

■  Keeping  time — Both  the  CLOCK  and  CONTROL  programs  that  come 
with  Windows  display  the  current  time.  The  timer  tells  the  programs 
when  to  update  the  clock.  The  DIGCLOCK  program,  described  later  in 
this  chapter,  uses  the  timer  to  display  a  digital  clock. 

■  Maintaining  an  updated  status  report — The  FREEMEM  program,  shown 
in  this  chapter,  uses  the  timer  to  display  available  memory  in  Windows. 

The  display  is  updated  every  second. 

■  Waking  up — The  Windows  CALENDAR  program  uses  the  timer  to  trigger 
a  preset  alarm. 

■  Multitasking — Windows  is  a  nonpreemptive  multitasking  environment, 
and  it  is  important  that  programs  return  control  to  Windows  as  quickly  as 
possible.  If  a  program  must  do  a  large  amount  of  processing,  it  can  divide 
the  job  into  smaller  pieces  and  process  each  piece  on  receipt  of  a 
WM-TIMER  message. 
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■  Implementing  an  “autosave”  feature — The  timer  can  prompt  a  Windows 
program  to  save  a  user’s  work  on  disk  whenever  a  specified  amount  of 
time  has  elapsed. 

■  Pacing  movement — Graphical  objects  in  a  game  or  successive  displays  in 
a  computer-assisted  instruction  program  may  need  to  proceed  at  a  set 
rate.  Using  the  timer  eliminates  the  inconsistencies  that  might  result  from 
variations  in  microprocessor  speed. 

■  Terminating  demonstration  versions  of  programs — Some  demonstration 
versions  of  programs  are  designed  to  terminate,  say,  30  minutes  after  they 
begin.  The  timer  can  signal  such  applications  when  the  time  is  up. 

■  Using  serial  or  parallel  communications — Unlike  most  other  input 
devices  in  Windows,  serial  or  parallel  communications  ports  do  not 
generate  messages.  Rather,  these  programs  must  poll  for  input,  and  the 
timer  can  tell  them  when  to  do  so.  (An  alternative  to  using  the  timer  for 
polling  involves  a  message  loop  built  around  the  PeekMessage  call.  This 
technique  is  discussed  in  Chapter  15.) 

This  chapter  also  explores  topics  that  extend  beyond  the  timer  to  other  areas  of  Win¬ 
dows  programming.  Foremost  among  these  topics  is  that  of  “call-back”  functions.  To  the 
uninitiated,  these  important  functions  might  seem  to  work  in  mysterious  ways,  and  the 
timer  is  not  the  only  place  you  will  encounter  them.  This  chapter  also  discusses  what  to  do 
when  a  program  cannot  gain  access  to  a  timer — a  problem  that  occurs  because  Windows 
maintains  only  a  limited  number  of  timers.  Solving  this  problem  is  fundamental  to  working 
with  the  Windows  timer,  but  the  method  presented  here  can  also  be  applied  to  error 
handling  in  other  programs.  Finally,  the  sample  programs  shown  here  deal  with  such  de¬ 
cidedly  nontimer  issues  as  Windows’  use  of  color,  using  a  type  of  window  known  as  a 
“popup,”  forcing  an  application  to  be  loaded  as  an  icon,  obtaining  the  amount  of  free 
memory  available  in  Windows,  using  floating-point  mathematics  in  your  Windows  pro¬ 
grams,  and  accessing  the  WIN. INI  file  to  obtain  information  about  international  time  and 
date  formats. 


TIMER  BASICS 

You  can  allocate  a  timer  for  your  Windows  program  by  calling  the  SetTimer  function.  Set- 
Timer  includes  a  parameter  specifying  an  interval  that  can  range  (in  theory)  from  1  msec 
(millisecond)  to  65,535  msec  (or  about  65.5  seconds).  The  value  indicates  the  rate  at  which 
Windows  sends  your  program  WM -TIMER  messages.  For  instance,  an  interval  of  1000 
msec  causes  Windows  to  send  your  program  a  WM -TIMER  message  every  second. 
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When  your  program  is  done  using  the  timer,  it  calls  the  KillTimer  function  to  stop 
the  timer  messages.  You  can  program  a  “one-shot”  timer  by  calling  KillTimer  during  the 
processing  of  the  WM_TIMER  message.  The  KillTimer  call  purges  the  message  queue  of 
any  pending  WM -TIMER  messages.  Your  program  will  never  receive  a  stray  WM -TIMER 
message  following  a  KillTimer  call. 

Windows  allows  only  32  timers  to  be  active  at  one  time.  If  all  32  timers  are  already 
allocated,  SetTimer  returns  NULL.  Windows  programs  that  use  a  timer  must  include  some 
way  to  deal  with  this  problem. 

SYSTEM.DRV  and  the  Windows  Tinier 

The  Windows  timer  is  a  relatively  simple  extension  of  the  timer  logic  built  into  the  IBM  PC’s 
hardware  and  ROM  BIOS.  The  PCs  ROM  BIOS  initializes  an  Intel  8259  timer  chip  to  gener¬ 
ate  the  hardware  Interrupt  08H.  This  interrupt  is  sometimes  called  the  “clock  tick”  or 
“timer  tick”  interrupt.  An  Interrupt  08H  occurs  every  54.925  msec,  or  about  18.2  times  per 
second.  Among  other  purposes,  the  BIOS  uses  Interrupt  08H  to  update  a  “time-of-day” 
value  stored  in  the  BIOS  data  area.  MS-DOS  uses  this  value  to  calculate  the  current  time. 

The  SYSTEM.DRV  driver  located  in  the  SYSTEM  subdirectory  of  your  Windows 
directories  handles  hardware  timer  interrupts.  SYSTEM.DRV  sets  a  new  Interrupt  08H  vec¬ 
tor  address  during  initialization  and  restores  the  original  vector  address  before  Windows 
terminates.  The  Interrupt  08H  routine  within  SYSTEM.DRV  calls  the  original  Interrupt  08H 
handler  before  doing  its  own  processing  so  that  underlying  system  functions  that  require 
this  interrupt  will  continue  to  work  normally. 

When  SYSTEM.DRV  receives  an  Interrupt  08H,  it  calls  a  routine  within  the  USER 
module  of  Windows  that  decrements  counters  for  each  timer  set  by  Windows  applications. 
When  a  counter  reaches  0,  USER  places  a  WM -TIMER  message  in  that  application’s  mes¬ 
sage  queue  and  resets  the  counter  to  the  original  value. 

Because  a  Windows  application  retrieves  WM -TIMER  messages  from  the  normal 
message  queue,  you  never  have  to  worry  about  your  program  being  “interrupted”  by  a  sud¬ 
den  WM-TIMER  message  while  doing  other  processing.  In  this  way,  the  timer  is  similar  to 
the  keyboard  and  mouse:  The  driver  handles  the  asynchronous  hardware  interrupt  events, 
and  Windows  translates  these  events  into  orderly,  structured,  serialized  messages. 

SYSTEM.DRV  does  not  attempt  to  reprogram  the  8259  timer  chip  in  the  IBM  PC.  The 
Windows  timer  has  the  same  54.925 -msec  resolution  as  the  underlying  PC  timer.  This  fact 
has  two  important  implications: 

■  A  Windows  application  cannot  receive  WM-TIMER  messages  at  a  rate 
faster  than  about  18.2  times  per  second  when  using  a  single  timer. 

■  The  time  interval  you  specify  in  the  SetTimer  call  is  always  rounded 
down  to  an  integral  multiple  of  clock  ticks.  For  instance,  a  1000-msec 
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interval  divided  by  54.925  msec  is  18.207  clock  ticks,  which  is  rounded 
down  to  18  clock  ticks,  which  is  really  a  989-msec  interval.  For  inter¬ 
vals  shorter  than  55  msec,  each  clock  tick  generates  a  single  WM_TIMER 
message. 

Do  not  attempt  to  intercept  the  ROM  BIOS  timer  interrupt  in  your  Windows  pro¬ 
grams.  Use  the  Windows  timer  instead. 

Timer  Messages  Are  Not  Asynchronous 

Non-Windows  programs  written  for  the  IBM  PC  and  compatibles  can  use  the  timer  tick  in¬ 
terrupt  by  intercepting  Interrupt  08H  or  Interrupt  1CH  (a  software  interrupt  called  by  the 
BIOS  Interrupt  08H  handler).  When  the  hardware  interrupt  occurs,  the  program  currently 
running  is  suspended,  and  control  passes  to  the  interrupt  handler.  When  the  interrupt  han¬ 
dler  is  done,  it  passes  control  back  to  the  interrupted  program. 

Like  the  hardware  keyboard  and  mouse  interrupts,  the  hardware  timer  tick  interrupt 
is  sometimes  called  an  asynchronous  interrupt  because  it  occurs  randomly  with  respect  to 
the  program  that  it  interrupts.  (Actually,  the  term  isochronous  is  more  accurate  than  asyn¬ 
chronous  for  a  timer  interrupt  because  the  interrupts  occur  at  equal  intervals.  But  the  inter¬ 
rupts  are  still  asynchronous  with  respect  to  other  processing.) 

Although  the  SYSTEM. DRV  driver  also  handles  asynchronous  Interrupt  08H  clock 
ticks,  the  WM_TIMER  messages  that  Windows  sends  to  applications  are  not  asynchronous. 
The  WM -TIMER  messages  are  placed  in  the  normal  message  queue  and  ordered  with  all 
the  other  messages.  Therefore,  if  you  specify  1000  msec  in  the  SetTimer  call,  your  program 
is  not  guaranteed  to  receive  a  WM -TIMER  message  every  second  or  even  (as  I  mentioned 
above)  every  989  msec.  If  another  application  is  busy  for  more  than  a  second,  your  pro¬ 
gram  will  not  get  any  WM-TIMER  messages  during  that  time.  Only  when  the  other  appli¬ 
cation  yields  control  to  Windows  (by  calling  GetMessage,  PeekMessage ,  or  WaitMessage) 
will  your  program  retrieve  its  next  WM-TIMER  message  from  the  queue. 

You  can  easily  demonstrate  this  to  yourself  with  the  CLOCK  program  included  with 
Windows  or  with  the  sample  programs  shown  in  this  chapter.  If  another  program  has  a 
long  paint  job  and  does  not  immediately  relinquish  control,  CLOCK  will  stop.  When 
CLOCK  regains  control,  it  will  jump  ahead  to  the  correct  time.  In  fact,  Windows  handles 
WM_TIMER  messages  much  like  WM-PAINT  messages.  Both  these  messages  are  low  pri¬ 
ority.  If  a  program’s  message  queue  contains  only  WM-PAINT  or  WM_TIMER  messages 
and  if  another  program’s  message  queue  contains  messages  other  than  WM -PAINT  or 
WM_TIMER,  Windows  will  pass  control  to  the  other  application. 

The  WM_TIMER  messages  are  similar  to  WM_PAINT  messages  in  another  respect: 
Windows  does  not  keep  loading  up  the  message  queue  with  multiple  WM -TIMER  mes¬ 
sages.  Instead,  Windows  combines  several  WM -TIMER  messages  in  the  message  queue 
into  a  single  message.  Therefore,  the  application  won’t  get  a  bunch  of  them  all  at  once, 
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although  it  may  get  two  WM_TIMER  messages  in  quick  succession.  An  application  cannot 
determine  the  number  of  “missing”  WM_TIMER  messages  that  result  from  this  process. 

When  CLOCK  regains  control  and  jumps  ahead  to  the  correct  time,  it  isn’t  because  it 
gets  several  WM_TIMER  messages  in  a  row.  CLOCK  must  determine  the  actual  time  and 
then  set  itself.  The  WM -TIMER  messages  only  inform  CLOCK  when  it  should  be  updated. 
A  program  can’t  keep  time  itself  solely  by  counting  WM -TIMER  messages.  (Later  in  this 
chapter,  we’ll  write  a  clock  application  that  updates  every  second,  and  we’ll  see  precisely 
how  this  is  accomplished.) 

For  convenience,  I’ll  be  talking  about  the  timer  in  terms  such  as  “getting  a 
WM-TIMER  message  every  second.”  But  keep  in  mind  that  these  messages  are  not  precise 
clock  tick  interrupts. 

USING  THE  TIMER:  THREE  METHODS 

If  you  need  a  timer  for  the  entire  duration  of  your  program,  you’ll  probably  call  SetTimer 
from  the  WinMain  function  or  while  processing  the  WM -CREATE  message,  and  KillTimer 
in  response  to  a  WM-DESTROY  message.  Setting  the  timer  in  WinMain  provides  the 
easiest  error  handling  if  a  timer  is  unavailable.  You  can  use  a  timer  in  one  of  three  ways, 
depending  on  the  parameters  to  the  SetTimer  call. 

Method  One 

This  method,  the  easiest,  causes  Windows  to  send  WM_TIMER  messages  to  the  normal 
window  procedure  of  the  application.  The  SetTimer  call  looks  like  this: 

SetTimer  (hwnd,  1,  wMsecInterval ,  NULL)  ; 

The  first  parameter  is  a  handle  to  the  window  whose  window  procedure  will  receive  the 
WM_TIMER  messages.  The  second  parameter  is  the  timer  ID,  which  should  be  a  nonzero 
number.  I  have  arbitrarily  set  it  to  1  in  this  example.  The  third  parameter  is  a  WORD  (16-bit 
unsigned  integer)  that  specifies  an  interval  in  milliseconds.  The  largest  value  (65535)  will 
deliver  a  WM -TIMER  message  about  once  a  minute. 

You  can  stop  the  WM -TIMER  messages  at  any  time  (even  while  processing  a 
WM_TIMER  message)  by  calling: 

KillTimer  (hwnd,  1)  ; 

The  second  parameter  is  the  same  timer  ID  used  in  the  SetTimer  call.  You  should  kill  any 
active  timers  in  response  to  a  WM -DESTROY  message  before  your  program  terminates. 

When  your  window  procedure  receives  a  WM -TIMER  message,  wParam  is  equal  to 
the  timer  ID  (which  in  the  above  case  is  simply  1),  and  IParam  is  0.  If  you  need  to  set 
more  than  one  timer,  use  a  different  timer  ID  for  each  timer.  The  value  of  wParam  will 
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differentiate  the  WM_TIMER  messages  passed  to  your  window  procedure.  To  make  your 
program  more  readable,  you  may  want  to  use  # define  statements  for  the  different  timer 
IDs: 


#define  TIMER_SEC  1 
#define  TI MER_M I N  2 

You  can  then  set  the  two  timers  with  two  SetTimer  calls: 

SetTimer  (hwnd,  TIMER_SEC,  1000,  NULL)  ; 

SetTimer  (hwnd,  TIME R_M I N ,  60000,  NULL)  ; 

The  WM -TIMER  logic  might  look  something  like  this: 

case  WM_T I MER  : 

switch  (wParam) 

{ 

case  TIMER_SEC  : 

[once-per-second  processing] 
break  ; 

case  TIME R_M I N  : 

[once-per-minute  processing] 
break  ; 

} 

return  0  ; 

If  you  want  to  set  an  existing  timer  to  a  different  elapsed  time,  kill  the  timer  and  call 
SetTimer  again.  This  code  assumes  that  the  timer  ID  is  1: 

Kill  Timer  (hwnd,  1)  ; 

SetTimer  (hwnd,  1,  wMsecInterval ,  NULL)  ; 

The  wMsecInterval  parameter  is  the  new  elapsed  time  in  milliseconds.  The  Windows 
CLOCK  application  uses  this  method  to  change  the  timer  from  1000  msec  to  60,000  msec 
when  it  becomes  an  icon.  As  an  icon,  CLOCK  needs  to  update  the  clock  every  minute 
rather  than  every  second.  When  it  is  expanded  from  an  icon  to  a  window,  CLOCK  changes 
the  timer  back  to  1000  msec. 

What  to  do  if  no  timer  is  available 

Windows  allows  only  32  timers  to  be  active  at  any  time.  If  no  timer  is  available,  SetTimer 
returns  NULL.  Your  program  might  be  able  to  function  reasonably  well  without  the  timer, 
but  if  you  need  the  timer  (as  CLOCK  certainly  does),  the  application  has  no  choice  but  to 
terminate  if  it  can’t  get  one.  If  you  call  SetTimer  in  WinMain,  you  can  terminate  the  pro¬ 
gram  simply  by  returning  FALSE  from  WinMain. 

Let’s  assume  you  want  a  1000-msec  timer.  Following  the  CreateWindow  call  but 
before  the  message  loop,  you  might  have  a  statement  like  this: 
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if  (ISetTimer  (hwnd,  1,  1000,  NULL)) 
return  FALSE  ; 

This  is  the  unfriendly  way  to  terminate.  The  user  is  left  wondering  why  the  application  will 
not  load.  It’s  much  friendlier — and  fairly  easy — to  use  a  Windows  message  box  for  display¬ 
ing  a  message.  A  complete  discussion  of  message  boxes  awaits  you  in  Chapter  10,  but  this 
will  get  you  started. 

A  message  box  is  a  popup  window  that  always  appears  in  the  center  of  the  display. 
Message  boxes  have  a  caption  bar  but  no  sizing  border.  The  caption  bar  usually  contains 
the  name  of  the  application.  The  message  box  encloses  a  message  and  one,  two,  or  three 
buttons  (some  combination  of  OK,  Retry,  Cancel,  Yes,  No,  and  others).  The  message  box 
can  also  contain  a  predefined  icon:  a  lowercase  “i”  (which  stands  for  “information”),  an  ex¬ 
clamation  point,  a  question  mark,  or  a  stop  sign.  You  have  probably  seen  plenty  of  message 
boxes  when  working  with  Windows. 

This  code  creates  an  informatory  message  box  that  you  can  use  when  SetTimer  fails 
to  allocate  a  timer: 

if  ( ! SetTimer  (hwnd,  1,  1000,  NULL)) 

{ 

MessageBox  (hwnd, 

"Too  many  clocks  or  timers!", 

"Program  Name", 

MB_I CON EXC LAMAT ION  !  MB_0K)  ; 
return  FALSE  ; 

1 

This  message  box  is  shown  in  Figure  5-1.  When  the  user  presses  Enter  or  clicks  the  OK 
button,  WinMain  terminates  by  returning  FALSE. 


Too  n 

nany  clocks  or  timers! 

0*  1 

Figure  5-1 .  A  message  box  for  “friendly  termination.  ” 

By  default,  message  boxes  are  “application  modal”  windows.  This  means  that  a  user  must 
respond  to  the  message  box  before  the  application  will  continue.  However,  the  user  can 
switch  to  other  applications  by  pressing  Alt-Tab  or  Alt-Esc  or  by  clicking  the  mouse  in  the 
window  of  another  program. 

Why  not  give  the  user  the  opportunity  to  close  one  of  the  other  applications  using 
the  timer  and  successfully  load  your  application?  That’s  what  this  code  does: 
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while  ( ! SetTimer  (hwnd,  1.  1000,  NULL)) 

if  ( IDCANCEL  ==  MessageBox  (hwnd, 

"Too  many  clocks  or  timers!", 

"Program  Name", 

MB_I CON EXC LAMAT ION  !  MB.RETRYCANCEL) ) 
return  FALSE  ; 

This  message  box,  shown  in  Figure  5-2,  has  two  buttons,  labeled  Retry  and  Cancel.  If  the 
user  selects  Cancel,  the  MessageBox  function  returns  a  value  equal  to  IDCANCEL,  and 
the  program  terminates.  If  the  user  selects  Retry,  SetTimer  is  called  again. 


m 


Program  Name 


Too  many  clocks  or  timers! 


Figure  5-2.  A  message  box  that  offers  a  choice. 

A  sample  program 

Figure  5-3  shows  a  sample  program  that  uses  the  timer.  This  program,  called  BEEPER1,  sets 
a  timer  for  1-second  intervals.  When  it  receives  a  WM_TIMER  message,  it  alternates  color¬ 
ing  the  client  area  blue  and  red,  and  it  beeps  by  calling  the  function  MessageBeep. 
(Although  MessageBeep  is  documented  as  a  companion  to  MessageBox ,  it’s  really  an  all¬ 
purpose  beep  function.  The  UINT  parameter  to  MessageBeep  can  be  any  value.)  BEEPER1 
sets  the  timer  in  the  WinMain  function  and  processes  the  WM -TIMER  messages  in  the 
WndProc  window  procedure.  During  the  WM -TIMER  message,  BEEPER1  calls  Mes¬ 
sageBeep,  inverts  the  value  of  bFlipFlop ,  and  invalidates  the  window  to  generate  a  WM- 
_PAINT  message.  During  the  WM-PAINT  message,  BEEPER1  obtains  a  RECT  structure  for 
the  size  of  the  window  by  calling  GetClientRect  and  colors  the  window  by  calling  FillRect. 

BEEPER1.MAK 

# . 

#  BEEPERl.MAK  make  file 

#  . 

beeperl.exe  :  beeperl.obj  beeperl.def 

$(WINLINK)  beeperl,  beeperl,  NUL,  $( WINLIB) ,  beeperl 
rc  -t  beeperl.exe 

beeperl.obj  :  beeperl. c 
$ ( W I NCC )  beeperl. c 

Figure  5-3.  The  BEEPER  1  program. 
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BEEPER1.C 

/* . - - - 

BEEPER1.C  '  --  Timer  Demo  Program  No.  1 
(c)  Charles  Petzold,  1992 
. - . . */ 


#include  <windows.h> 
#define  ID.TIMER  1 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Beeperl"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. IpszMenuName 
wndclass. IpszClassName 


CS.HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL.  I DI_APP LI CATI ON )  ; 
LoadCursor  (NULL.  IDC.ARR0W)  ; 
GetStockObject  (WHITE.BRUSH)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 

} 


hwnd  =  CreateWindow  (szAppName,  "Beeperl  Timer  Demo", 
WS.OVERLAPP EDWIN DOW, 
CW.USEDEFAULT,  CW.USEDEFAULT, 
CW.USEDEFAULT,  CW.USEDEFAULT, 
NULL,  NULL,  hlnstance,  NULL)  ; 


while  USetTimer  (hwnd,  ID.TIMER,  1000,  NULL)) 
if  ( IDCANCEL  ==  MessageBox  (hwnd, 

"Too  many  clocks  or  timers!",  szAppName, 
MB_I CONEXC LAMATION  !  MB.RETRYCANCEL) ) 

return  FALSE  ; 


(continued) 
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ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  ( &msg )  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg. wParam  ; 

} 

long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  BOOL  fFlipFlop  =  FALSE  ; 

HBRUSH  hBrush  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

RECT  rc  ; 

switch  (message) 

{ 

case  WM_TI ME R  : 

MessageBeep  (0)  ; 

fFlipFlop  =  ! f FI ipFl op  ; 

InvalidateRect  (hwnd,  NULL,  FALSE)  ; 

return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

GetClientRect  (hwnd,  &rc)  ; 

hBrush  =  CreateSol idBrush  (fFlipFlop  ?  RGB( 255 ,0,0)  : 

RGB(0, 0,255))  ; 

Fill Rect  (hdc,  &rc,  hBrush)  ; 

EndPaint  (hwnd,  &ps)  ; 

DeleteObject  (hBrush)  ; 
return  0  ; 

case  WM_DESTROY  : 

Kill  Timer  (hwnd,  ID_TIMER)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 
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BEEPER1.DEF 


BEEPERl . DEF  module  definition  file 


NAME 


BEEPERl 


DESCRIPTION  'Timer  Demo  Program  No.  1  (c)  Charles  Petzold,  1992' 
EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


Because  BEEPERl  audibly  indicates  every  WM  -TIMER  message  it  receives,  you  can 
get  a  good  idea  of  the  erratic  nature  of  WM_TIMER  messages  by  loading  BEEPERl  and  per¬ 
forming  some  other  actions  within  Windows.  For  instance,  try  moving  or  resizing  the 
BEEPERl  window.  This  causes  the  program  to  enter  a  “modal  message  loop.”  Windows 
prevents  anything  from  interfering  with  the  move  or  resize  operation  by  trapping  all  mes¬ 
sages  through  a  message  loop  inside  Windows  rather  than  the  message  loop  in  your  pro¬ 
gram.  Most  messages  to  a  program’s  window  that  come  through  this  loop  are  simply 
discarded,  which  is  why  BEEPERl  stops  beeping.  When  you  complete  the  move  or  resize, 
you’ll  note  that  BEEPERl  doesn’t  get  all  the  WM_TIMER  messages  it  has  missed,  although 
the  first  two  messages  may  be  less  than  a  second  apart. 

This  is  our  first  encounter  with  a  Windows  program  that  uses  color,  so  a  brief  look  at 
how  Windows  handles  color  is  worthwhile  here. 

Windows’  use  of  color 

Windows  uses  an  unsigned  long  (32-bit)  integer  value  to  represent  a  color.  The  lowest  three 
bytes  specify  red,  green,  and  blue  values  that  range  from  0  through  255,  as  illustrated  by 
Figure  5-4.  This  results  in  a  potential  palette  of  224  (or  about  16  million)  colors. 
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Figure  5-4.  The  32-bit  color  value. 

This  unsigned  long  is  often  referred  to  as  an  “RGB  color.”  The  WINDOWS.H  header 
file  provides  several  macros  for  working  with  RGB  color  values.  The  RGB  macro  in  WIN¬ 
DOWS.H  takes  three  arguments  representing  red,  green,  and  blue  values  and  combines 
them  into  an  unsigned  long: 
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//define  RGB(r,g,b)  ((DWORD) (( (BYTE) (r)  i  \ 

( (WORD) (g)  «  8))  !  \ 

( ( (DWORD) (BYTE) (b) )  «  16))) 

Thus,  the  value: 

RGB  (255,  0,  255) 

is  really  OxOOFFOOFF,  an  RGB  color  value  for  magenta.  When  all  three  arguments  are  set  to 
0,  the  color  is  black;  when  the  arguments  are  set  to  255,  the  color  is  white.  The  GetRValue , 
GetGValue ,  and  GetBValue  macros  extract  the  unsigned  character  primary-color  values 
from  an  unsigned  long  RGB  color  value.  These  macros  are  sometimes  handy  when  you’re 
using  Windows  functions  that  return  RGB  color  values  to  your  program. 

The  most  common  video  display  adapters  used  for  Windows  are  the  Enhanced 
Graphics  Adapter  (EGA)  and  Video  Graphics  Array  (VGA).  In  the  display  resolutions  that 
Windows  uses,  both  these  adapters  can  display  16  different  colors.  (Some  “Super  VGA” 
boards  can  display  256  different  colors  under  Windows,  although  normally  Windows  uses 
only  20  of  these  colors.  Making  use  of  the  other  236  colors  requires  use  of  the  Windows  pal¬ 
ette  manager.)  Windows  can  display  additional  colors  by  “dithering,”  which  is  creating  a 
pixel  pattern  that  combines  pixels  of  different  pure  colors. 

Not  all  unique  combinations  of  red,  green,  and  blue  bytes  produce  different  dither¬ 
ing  patterns.  For  instance,  on  a  color  EGA  or  VGA,  a  red,  green,  or  blue  value  must  gener¬ 
ally  be  incremented  by  4  to  produce  a  different  dithering  pattern.  So  for  these  adapters,  you 
have  218  (or  262,144)  dithered  colors. 

BEEPER1  uses  the  FillRect  function  to  color  its  client  area.  The  first  parameter  to 
FillRect  is  the  device  context  handle,  the  second  is  a  pointer  to  the  RECT  structure,  and  the 
third  is  a  handle  to  a  “brush.”  A  brush  is  a  graphics  object  that  Windows  uses  to  fill  an  area. 
Brushes  can  be  solid  colors  or  composed  of  various  hatchmarks  or  patterns. 

BEEPER1  creates  a  brush  of  a  solid  color  by  calling  CreateSolidBrush.  The  only  pa¬ 
rameter  is  an  RGB  color  value.  Depending  on  the  value  of  fFlipFlop ,  BEEPER  sets  this 
parameter  to  RGB(255,0,0),  which  is  red,  or  RGB(0, 0,255),  which  is  blue. 

A  brush  is  a  graphics  object.  If  you  create  a  brush,  you  must  also  delete  it  when  you’ve 
finished.  After  calling  FillRect ,  BEEPER1  deletes  the  brush  by  calling  DeleteObject. 

Method  Two 

The  first  method  for  setting  the  timer  causes  WM -TIMER  messages  to  be  sent  to  the  normal 
window  procedure.  With  this  second  method,  you  can  direct  Windows  to  send  the  timer 
messages  to  another  function  within  your  program. 

The  function  that  will  receive  these  timer  messages  is  termed  a  “call-back”  function. 
This  is  a  function  within  your  program  that  is  called  by  Windows.  You  tell  Windows  the  ad¬ 
dress  of  this  function  (well,  not  really  the  address  of  the  function,  but  we’ll  get  to  that),  and 
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Windows  later  calls  the  function.  This  should  sound  familiar  because  a  program’s  window 
procedure  is  really  a  type  of  call-back  function.  You  tell  Windows  the  address  of  the 
function  when  registering  the  window  class,  and  Windows  calls  the  function  when  send¬ 
ing  messages  to  the  program.  However,  call-back  functions  that  are  not  window  pro¬ 
cedures  must  be  handled  a  little  differently. 

SetTimer  is  not  the  only  Windows  function  that  uses  a  call-back  function.  The 
CreateDialog  and  DialogBox  functions  (discussed  in  Chapter  10)  use  call-back  functions 
to  process  messages  in  a  dialog  box;  several  Windows  functions  ( EnumChildWindows , 
EnumFonts ,  EnumObjects ,  EnumProps ,  and  EnumWindows )  pass  enumerated  information 
to  call-back  functions;  and  several  less-commonly  used  functions  ( GrayString ,  LineDDA , 
SetResourceHandler, ;  and  SetWindowsHook )  also  require  call-back  functions.  Call-back 
functions  are  often  a  major  hang-up  for  beginning  Windows  programmers.  Some  strange 
things  are  involved.  I’m  first  going  to  tell  you  how  to  use  call-back  functions,  and  then  I’ll 
tell  you  the  reasons  for  what  you’re  doing. 

Like  a  window  procedure,  a  call-back  function  must  be  defined  as  FAR  PASCAL 
-export  because  it  is  called  by  Windows  from  outside  the  code  segment  of  the  program. 
The  parameters  to  the  call-back  function  and  the  value  returned  from  the  call-back  func¬ 
tion  depend  on  the  purpose  of  the  call-back  function.  In  the  case  of  the  call-back  function 
associated  with  the  timer,  the  input  parameters  are  the  same  as  the  input  parameters  to  a 
window  procedure.  The  timer  call-back  function  returns  a  UINT  value  to  Windows. 

Let’s  name  the  call-back  function  TimerProc.  (You  can  name  it  anything  you  like.) 
It  will  process  only  WM-TIMER  messages. 


UINT  FAR  PASCAL  .export  TimerProc  ( HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


{ 


[process  WM-TIMER  messages] 
return  0  ; 

} 


The  hwnd  input  parameter  is  the  handle  to  the  window  specified  when  you  call  SetTimer. 
Windows  will  send  only  WM_TIMER  messages  to  TimerProc ,  so  the  message  parameter 
will  always  equal  WM_TIMER.  The  wParam  value  is  the  timer  ID,  and  the  IParam  value  is 
the  system  time. 

As  I  noted  earlier,  the  first  method  for  setting  a  timer  requires  a  SetTimer  call  that 
looks  like  this: 


SetTimer  (hwnd,  1,  wMsecInterval ,  NULL)  ; 

When  you  use  a  call-back  function  to  process  WM_TIMER  messages,  the  fourth  parameter 
to  SetTimer  is  instead  the  far  address  of  the  call-back  function. 

But  not  really. 
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Now  listen  carefully:  The  far  address  that  you  must  pass  to  Windows  as  the  fourth 
parameter  of  the  SetTimer  call  is  not  the  address  of  the  function  within  the  program.  It  is 
instead  a  far  address  obtained  from  the  Windows  function  MakeProcInstance.  To  use 
MakeProcInstance,  first  define  a  variable  that  is  a  far  pointer  to  a  function.  You  can  use  the 
WINDOWS. H  identifier  FARPROC  for  this  definition: 

FARPROC  lpfnTimerProc  ; 

In  WinMain  (or  any  other  section  of  your  program  that  is  executed  only  once  for 
each  instance),  call  MakeProcInstance.  The  parameters  to  MakeProcInstance  are  the  ad¬ 
dress  of  TimerProc  and  the  value  of  hlnstance.  MakeProcInstance  returns  a  far  pointer 
that  you  save  in  lpfnTimerProc. 

lpfnTimerProc  =  MakeProcInstance  ((FARPROC)  TimerProc,  hlnstance)  ; 

You  can  now  use  this  lpfnTimerProc  value  when  you  call  SetTimer. 

SetTimer  (hwnd,  1,  wMsecInterval ,  1 pfnTimerProc)  ; 

You’re  done.  Now  that’s  not  too  bad,  is  it? 

A  sample  program 

Let’s  look  at  some  sample  code  so  you  can  see  how  this  stuff  fits  together.  Then  we’ll  ex¬ 
plore  MakeProcInstance  some  more.  The  BEEPER2  program,  shown  in  Figure  5-5,  is  func¬ 
tionally  the  same  as  BEEPER1  except  that  Windows  sends  the  timer  messages  to  TimerProc 
rather  than  WndProc.  To  tell  the  C  compiler  that  TimerProc  is  a  function  so  that  we  can  use 
the  name  of  the  function  when  calling  MakeProcInstance ,  we  declare  TimerProc  at  the  top 
of  the  program  along  with  WndProc.  Notice  that  the  program  calls  MakeProcInstance  for 
each  instance. 

BEEPER2.MAK 

# . - . 

#  BEEPER2.MAK  make  file 

#  . 

beeper2.exe  :  beeper2.obj  beeper2.def 

$ ( WI NLI NK)  beeper2,  beeper2,  NUL,  $(WINLIB),  beeper2 
rc  -t  beeper2.exe 

beeper2.obj  :  beeper2.c 
$ ( WI NCC )  beeper2.c 

Figure  5-5.  The  BEEPER2 program. 
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BEEPER2.C 

/* .  . . 

BEEPER2.C  --  Timer  Demo  Program  No.  2 
(c)  Charles  Petzold,  199? 

. - . */ 

//include  <windows.h> 

//define  ID.TIMER  1 

long  FAR  PASCAL  .export  WndProc  (HWND,  HINT,  UINT.  LONG)  ; 

UINT  FAR  PASCAL  .export  TimerProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Beeper2”  ; 

FARPROC  lpfnTimerProc  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

wndclass.cbWndExtra  =0  ; 

wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  Loadlcon  (NULL,  I DI_APP LI  CATION )  ; 

wndclass. hCursor  =  LoadCursor  (NULL,  IDC.ARR0W)  ; 

wndclass. hbrBackground  =  GetStockObject  (WHITE.BRUSH)  ; 

wndclass. IpszMenuName  =  NULL  ; 

wndclass. IpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  ”Beeper2  Timer  Demo”, 

WS.OV ERLAPP EDW I NDOW , 

CW.USEDEFAULT,  CW.USEDEFAULT, 

CW.USEDEFAULT,  CW.USEDEFAULT. 

NULL.  NULL,  hlnstance,  NULL)  ; 

lpfnTimerProc  =  MakeProcInstance  ((FARPROC)  TimerProc,  hlnstance)  ; 

while  (ISetTimer  (hwnd,  ID.TIMER,  1000,  lpfnTimerProc)) 
if  (IDCANCEL  ==  MessageBox  (hwnd, 

( continued) 
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"Too  many  clocks  or  timers!",  szAppName, 
MB_I CON EXC LAMAT ION  !  MB.RETRYCANCEL) ) 

return  FALSE  ; 

ShowWindow  (hwnd,  nCmdShow)  ;  * 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM.DESTROY  : 

Kil 1  Timer  (hwnd,  I D_T I M E R )  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

UINT  FAR  PASCAL  .export  TimerProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  BOOL  fFlipFlop  =  FALSE  ; 

HBRUSH  hBrush  ; 

HDC  hdc  ; 

RECT  rc  ; 

MessageBeep  (0)  ; 
fFlipFlop  =  IfFlipFlop  ; 

GetClientRect  (hwnd,  &rc)  ; 

hdc  =  GetDC  (hwnd)  ; 

hBrush  =  CreateSol idBrush  (fFlipFlop  ?  RGB(255,0,0)  :  RGB(0, 0,255) ) 

Fill Rect  (hdc,  &rc,  hBrush)  ; 

ReleaseDC  (hwnd,  hdc)  ; 

DeleteObject  (hBrush)  ; 

return  0  ; 

} 
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BEEPER2.DEF 


BEEPER2.DEF  module  definition  file 


NAME 


BEEPER2 


DESCRIPTION  'Timer  Demo  Program  No.  2  (c)  Charles  Petzold,  1992' 
EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


Proper  handling  of  call-back  functions 

Here  are  the  two  rules  for  call-back  functions.  Any  function  within  your  program  that  is 
called  by  Windows  is  handled  as  follows: 

1.  The  function  should  be  defined  as  FAR  PASCAL  -export. 

2.  The  address  of  the  function  that  you  give  to  Windows  is  the  return  value 
from  a  MakeProcInstance  call.  (This  rule  does  not  apply  to  window 
procedures  that  are  passed  to  Windows  as  part  of  a  window’s  class 
structure  in  a  RegisterClass  c all.  Windows  itself  handles  the  MakeProc¬ 
Instance  requirement  in  this  case.) 

These  rules  originated  back  in  the  days  of  Windows  1.0,  when  Windows  ran  ex¬ 
clusively  in  real  mode  on  the  8088  and  80286  microprocessors.  They  were  part  of  the 
overhead  necessary  for  Windows  to  run  several  instances  of  the  same  program  using  the 
same  code  segment,  where  each  instance  must  have  its  own  data  segment.  Windows  also 
required  this  overhead  to  move  the  code  segment  and  the  data  segments  around  in 
memory.  Here  are  the  practical  results  of  the  two  rules: 

1.  When  you  define  a  function  as  FAR  and  you  compile  with  the  -Gw 
(Windows)  flag,  the  compiler  inserts  special  prolog  and  epilog  code  in 
the  function.  In  assembly  language,  the  prolog  code  sets  the  value  of  the 
AX  register  equal  to  the  DS  (data  segment)  register  using  a  MOV  AX,  DS 
instruction.  It  then  saves  the  value  of  DS  (with  PUSH  DS)  and  sets  DS 
equal  to  AX  using  a  MOV  DS,  AX  instruction.  The  epilog  code  at  the  end 
of  the  function  pops  the  original  value  of  DS  off  the  stack. 
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2.  If  a  FAR  function  is  also  exported  (that  is,  the  function  is  defined  using 
the  -export  keyword,  Windows  replaces  the  MOV  AX,  DS  instruction  at 
the  top  of  the  function  prolog  with  NOP  (no  operation)  instructions  when 
the  code  segment  is  loaded  into  memory.  With  this  change  the  function 
sets  DS  from  the  value  of  AX.  But  what  is  the  value  of  AX  on  entry  to  the 
function?  Well,  if  you  didn’t  do  anything  else,  the  value  of  AX  would  be 
indeterminate.  So  would  the  operation  of  your  program. 

3.  MakeProcInstance  creates  a  small  piece  of  code — called  a  “thunk” — 
elsewhere  in  Windows.  The  far  address  returned  from  MakeProcInstance 
is  the  address  of  this  thunk.  The  thunk  loads  the  segment  address  of  the 
data  segment  in  AX  and  branches  to  the  function.  The  function  prolog 
then  loads  DS  from  AX.  Perfect. 

Note  that  MakeProcInstance  requires  hlnstance  as  a  parameter.  You  must  use 
MakeProcInstance  to  create  a  different  thunk  for  each  instance  because  each  instance  has 
its  own  data  segment.  For  a  particular  call-back  function,  the  thunks  for  each  instance  all 
branch  to  the  same  function  address  (because  all  instances  use  the  same  code  segment), 
but  each  thunk  sets  AX  to  a  different  data  segment — the  data  segment  for  that  instance. 
When  Windows  moves  a  data  segment  in  memory,  it  must  change  the  thunk  for  that  in¬ 
stance  so  that  the  thunk  sets  AX  to  the  new  data  segment  address.  The  thunk  itself  is 
always  in  an  unmoveable  area  of  memory. 

(To  further  complicate  this  matter,  any  reference  in  your  program  to  a  FAR  func¬ 
tion — such  as  the  address  passed  to  the  MakeProcInstance  call  and  the  address  that  the 
thunk  branches  to — is  not  even  the  address  of  the  function  within  your  program.  Another 
small  routine  sits  between  the  thunk  and  the  actual  function.  This  routine  loads  the  code 
segment  into  memory  if  it  has  not  yet  been  loaded  or  if  it  has  been  discarded  from  memory.) 

These  rules  imply  that  you  should  never  call  exported  far  functions  directly  from 
within  your  program.  For  instance,  you  might  want  to  simulate  a  timer  message  with  the 
following  statement: 

TimerProc  (hwnd,  WM_TIMER,  1,  0L)  ;  //  WRONG  !!! 

It  looks  OK,  but  don’t  do  it!  The  prolog  of  TimerProc  will  set  DS  equal  to  AX,  but  the  value 
of  AX  could  be  anything,  and  it  very  likely  is  not  the  segment  address  of  the  program’s  data 
segment.  If  you  need  to  directly  call  an  exported  function  from  within  your  program,  use 
the  far  pointer  returned  from  MakeProcInstance : 

(*1 pfnTimerProc)  (hwnd,  WM_TIMER,  1,  0L)  ;  //  RIGHT 

This  code  calls  the  thunk,  and  the  thunk  sets  AX  equal  to  the  correct  data  segment  before 
branching  to  the  function. 
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Things  have  changed  a  bit  in  recent  years,  however.  Windows  3.0  supported  the 
operation  of  Windows  and  Windows  applications  in  protected  mode.  Some  developers  de¬ 
cided  to  avoid  real  mode  entirely.  Windows  3.1  continues  this  trend  by  removing  real  mode 
support  altogether.  While  these  rules  can  be  broken  for  applications  that  run  only  in  pro¬ 
tected  mode,  it’s  probably  best  to  continue  to  observe  them.  I’ll  have  more  to  say  on  this 
subject  in  Chapter  7. 

Method  Three 

The  third  method  of  setting  the  timer  is  similar  to  the  second  method.  It  requires  a  far 
pointer  created  from  MakeProcInstance  to  a  function  that  processes  the  WM -TIMER 
messages.  However,  the  hwnd  parameter  to  SetTimer  is  set  to  NULL,  and  the  second 
parameter  (normally  the  timer  ID)  is  ignored.  Instead,  the  function  returns  a  timer  ID: 

nTimerlD  =  SetTimer  (NULL,  0,  wMsecInterval ,  1 pfnTimerProc)  ; 

The  nTimerlD  returned  from  SetTimer  will  be  NULL  if  no  timer  is  available. 

The  first  parameter  to  KillTimer  (usually  the  window  handle)  must  also  be  NULL. 
The  timer  ID  must  be  the  value  returned  from  SetTimer. 

KillTimer  (NULL,  nTimerlD)  ; 

The  hwnd  parameter  passed  to  the  TimerProc  timer  function  will  also  be  NULL.  The 
wParam  parameter  is  the  timer  ID,  and  IParam  is  IpfnTimerProc ,  the  same  as  in  the  sec¬ 
ond  method. 

This  method  for  setting  a  timer  is  rarely  used.  It  might  come  in  handy  if  you  do  a  lot  of 
SetTimer  calls  at  different  times  in  your  program  and  don’t  want  to  keep  track  of  which 
timer  IDs  you’ve  already  used. 

Now  that  you  know  how  to  use  the  Windows  timer,  you’re  ready  for  a  couple  of  useful 
timer  programs. 


USING  THE  TIMER  FOR  A  STATUS  REPORT 

One  use  of  a  Windows  timer  is  to  periodically  update  a  status  report  displayed  on  the 
screen.  The  program  can  relinquish  control  until  the  next  WM -TIMER  message  and  thus 
not  hog  precious  processing  time.  The  FREEMEM  program,  shown  in  Figure  3-6  on  the  fol¬ 
lowing  pages,  displays  the  amount  of  free  memory  available  in  Windows  in  megabytes.  The 
free  memory  value  is  updated  every  second  and  is  consistent  with  the  figure  shown  in  the 
Program  Manager’s  and  File  Manager’s  About  box.  FREEMEM  can  let  you  know  how  close 
Windows  is  to  running  out  of  memory.  While  testing  a  new  Windows  program,  you  may 
want  to  keep  an  eye  on  FREEMEM  for  a  rough  indication  of  how  your  program  is  allocating 
and  freeing  memory. 
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FREEMEM.MAK 

#- . . . 

#  FREEMEM.MAK  make  file 

#  . . . . 

freemem.exe  :  freemem.obj  freemem.def 

$(WINLINK)  freemem,  freemem,  NUL,  $(WINLIB),  freemem 
rc  -t  freemem.exe 

freemem.obj  :  freemem. c 
$ ( WI NCC )  freemem. c 


FREEMEM.C 

/* . 

FREEMEM.C  --  Free  Memory  Display  Program 
(c)  Charles  Petzold,  1992 
.  . */ 


♦include  <windows.h> 
♦include  <stdio.h> 

♦define  I D_T I M E R  1 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "FreeMem"  ; 

HDC  hdc  ; 

HWND  hwnd  ; 

MSG  msg  ; 

TEXTMETRIC  tm  ; 

WNDCLASS  wndclass  ; 


if  (hPrevInstance) 
return  FALSE  ; 


wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 


=  CS.HREDRAW  !  CS.VREDRAW  ; 
=  WndProc  ; 

=  0  ; 

=  0  ; 


Figure  5-6.  The  FREEMEM  program. 


(continued) 
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wndclass.hlnstance  =  hi  ns tance  ; 
wndclass.hlcon  =  NULL  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W) 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH) 
wndclass.lpszMenuName  =  NULL  ; 
wndclass.lpszClassName  =  szAppName  ; 


! Regi sterCl ass  (&wndclass)  ; 

hwnd  =  CreateWindow  (szAppName,  "Free  Memory", 
WS_OVERLAPP EDWIN DOW , 
CW.USEDEFAULT,  CWJJSEDEFAULT, 
CW_USEDEFAULT,  CW_USEDE FAU LT , 
NULL,  NULL,  hlnstance,  NULL)  ; 


hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 

ReleaseDC  (hwnd,  hdc)  ; 

if  (4  *  tm.tmAveCharWidth  >  GetSystemMetrics  (SM_CXIC0N)  !! 

2  *  tm.tmHeight  >  GetSystemMetrics  ( SM_CYIC0N ) ) 

{ 

MessageBox  (hwnd,  "Icon  size  too  small  for  display!", 
szAppName,  MB_I CON EXC LAMATION  !  MB_0K)  ; 
return  FALSE  ; 

} 

if  (ISetTimer  (hwnd.  I D_T I M E R ,  1000,  NULL)) 

{ 

MessageBox  (hwnd,  "Too  many  clocks  or  timers!", 

szAppName,  MB_I CONEXCLAMATI ON  !  MB_0K)  ; 
return  FALSE  ; 

} 

ShowWindow  (hwnd,  SW_SH0WM I NNOACT I V E )  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


(continued) 
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{ 

static  DWORD 
static  RECT 
char 
HDC 

PAINTSTRUCT 


dwFreeMem,  dwPrevMem  ; 
rect  ; 

cBuffer  [20]  ; 
hdc  ; 
ps  ; 


switch  (message) 

{ 

case  WM_TIMER  : 

dwFreeMem  =  GetFreeSpace  (0)  ; 

if  (dwFreeMem  !=  dwPrevMem) 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 

dwPrevMem  =  dwFreeMem  ; 
return  0  ; 

case  WM.SIZE  : 

GetClientRect  (hwnd,  &rect)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

DrawText  (hdc,  cBuffer, 

sprintf  (cBuffer,  "%.2f  megs", 

dwFreeMem  /  1024.0  /  1024.0), 
&rect ,  DT_WORDBREAK)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM.QUERYOPEN  : 
return  0  ; 

case  WM_DESTROY  : 

Kill  Timer  (hwnd,  I D_T I M  E  R )  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
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FREEMEM.DEF 


FREEMEM.DEF  module  definition  file 


NAME  FREEMEM 

DESCRIPTION  'Free  Memory  Display  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 

Because  FREEMEM  doesn’t  need  much  display  space,  I’ve  written  it  to  appear  as  an  icon  at 
the  bottom  of  the  Windows  screen.  (See  Figure  5-7.)  This  is  about  as  unobtrusive  a  window 
as  you  can  create  in  Windows. 


28.94 

iffi 

megs 

Program 

Manager 

FreeMemo.il 

Figure  5-7.  The  FREEMEM  icon. 

Although  FREEMEM’s  use  of  the  timer  is  simple  enough,  the  program  illustrates 
some  interesting  tricks  that  admittedly  have  nothing  to  do  with  the  timer. 

Creative  Use  of  Icons 

Unlike  most  Windows  programs,  FREEMEM  starts  out  life  as  an  icon,  displays  everything  it 
needs  to  display  within  the  icon,  and  cannot  be  opened  into  a  regular  window.  Most  Win¬ 
dows  applications  have  static  pictorial  icons  that  you  specify  in  the  windows  class  struc¬ 
ture.  These  icons  are  usually  created  with  the  Image  Editor  utility  supplied  with  the 
Windows  Software  Development  Kit  (as  you’ll  see  in  Chapter  8).  So  far,  we’ve  been  using 
predefined  Windows  icons  in  our  programs.  Alternatively,  you  can  specify  a  NULL  icon  in 
the  window  class  structure  with  the  statement: 

wndcl ass .hlcon  =  NULL  ; 

A  NULL  icon  means  that  the  application  is  responsible  for  drawing  the  icon.  Windows 
sends  the  application  WM_PAINT  messages  when  the  icon  needs  to  be  painted.  Thus,  a 
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program  can  change  the  appearance  of  the  icon  while  the  program  is  running.  The  CLOCK 
application  included  with  Windows  uses  this  technique  to  display  the  clock  even  when  the 
window  is  an  icon.  A  NULL  icon  is  really  just  a  tiny  window  that  you  can  draw  on  in  the 
same  way  that  you  draw  on  the  client  area  of  a  normal  window.  If  you  need  to  know  when 
your  application  is  becoming  an  icon,  you  can  get  the  information  from  the  tuParam  pa¬ 
rameter  of  a  WM_SIZE  message.  For  instance,  when  CLOCK  becomes  an  icon,  it  eliminates 
the  second  hand  from  the  clock  and  changes  the  timer  from  a  1-second  interval  to  a 
1-minute  interval.  A  program  can  also  determine  whether  its  window  is  iconic  by  calling 
the  Islconic  function. 

FREEMEM  displays  two  lines  of  text  within  its  icon.  This  will  work  fine  on  the  most 
common  displays  used  for  Windows,  but  it  may  not  work  for  some  high-resolution  boards 
that  may  use  a  larger  system  font.  Because  FREEMEM  cannot  display  correctly  on  these 
video  boards,  it  checks  the  size  of  the  system  font  against  the  icon  size  and  uses  a  message 
box  to  inform  the  user  if  the  icon  size  is  too  small. 

Forcing  the  Icon 

Shortly  before  entering  the  message  loop  in  WinMain, ,  most  Windows  applications  execute 
the  function: 

ShowWindow  (hwnd,  nCmdShow)  ; 

The  nCmdShow  variable  is  passed  to  the  program  as  a  parameter  to  WinMain . 

If  you  run  a  program  from  the  File  Manager  (by  selecting  Run  from  the  File  menu, 
pressing  Enter  when  the  cursor  is  on  the  program  name,  or  double-clicking  the  program), 
nCmdShow  is  set  equal  to  SW_SHOWNORMAL.  If  you  load  an  application  as  an  icon  (by 
selecting  the  Run  Minimized  option  in  the  Run  dialog  box  or  pressing  Shift-Enter  with  the 
cursor  on  the  program  name),  nCmdShow  is  set  equal  to  SW_SHOWMINNOACTIVE.  Your 
application  usually  doesn’t  have  to  figure  this  out  but  simply  passes  this  parameter  to 
ShowWindow. 

However,  you  aren’t  required  to  use  the  nCmdShow  variable  with  ShowWindow. 
Instead,  FREEMEM  uses  the  line: 

ShowWindow  (hwnd,  SW_SH0WM I NNOACT I V E )  ; 

This  forces  the  window  to  appear  as  an  icon  regardless  of  the  value  of  nCmdShow.  The 
active  program  remains  active. 

You  can  perform  other  tricks  with  this  technique.  If  you  always  want  a  particular 
application  to  appear  first  as  a  maximized  full-screen  display,  you  can  use: 

ShowWindow  (hwnd,  SW_SHOWMAX IMI ZED )  ; 
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Keeping  the  Icon  an  Icon 

FREEMEM  does  not  allow  itself  to  be  opened  into  a  regular  window.  Would  you  believe 
this  trick  requires  merely  two  simple  lines  in  the  WndProc  function?  Here  they  are: 

case  WM_QUERYOPEN  : 
return  0  ; 

These  two  lines  don’t  seem  to  be  doing  very  much,  but  let’s  take  a  closer  look. 

Windows  sends  a  WM_QUERYOPEN  message  to  a  program  when  it  wants  to  open  an 
icon  into  a  window.  Normally,  WM-QUERYOPEN  is  passed  on  to  the  DefWindowProc 
function,  which  returns  a  nonzero  value;  Windows  then  opens  the  icon.  With  the  two  lines 
shown  above,  however,  WndProc  returns  a  value  of  0  for  a  WM_QUERYOPEN  message.  So 
when  Windows  asks,  “Do  you  want  to  be  opened?”  WndProc  answers  “Zero,”  which  in  this 
case  means  “No  thanks.” 

Calculating  Free  Memory 

When  Windows  sends  FREEMEM  a  WM_TIMER  message,  FREEMEM  must  determine  the 
amount  of  free  memory.  Like  the  About  box  in  the  Program  Manager  and  File  Manager, 
FREEMEM  gets  a  free  memory  value  by  calling  GetFreeSpace  with  a  parameter  of  0.  The 
GetFreeSpace  function  is  new  in  Windows  3-  Prior  to  Windows  3,  Windows  programs  used 
GlobalCompact  with  a  parameter  of  0  to  obtain  the  largest  block  of  contiguous  free  memory 
in  the  system,  which  is  not  nearly  as  useful  as  the  total  amount  of  free  memory.  (Windows 
memory  management  is  covered  in  detail  in  Chapter  7.) 

If  the  free  memory  value  has  changed  since  the  last  GetFreeSpace  call,  FREEMEM 
invalidates  the  client  area  to  generate  a  WM_PAINT  message.  FREEMEM  processes  WM- 
_PAINT  messages  by  calling  DrawText,  a  convenient  function  for  simple  word-wrapped 
text.  FREEMEM  converts  the  free  memory  in  bytes  to  a  floating-point  value  in  megabytes, 
and  sprint f  stores  it  formatted  to  two  decimal  places. 

USING  THE  TIMER  FOR  A  CLOCK 

A  clock  is  the  most  obvious  application  for  the  timer.  Although  digital  clocks  were  once  in 
fashion,  the  pendulum  has  swung  back  (so  to  speak)  to  analog  clocks.  But  you  already  have 
an  analog  clock  with  Windows.  Although  the  CLOCK  program  has  a  digital-clock  setting, 
I’m  going  to  write  a  good  old  digital-clock  program — because  it  provides  an  interesting 
example  of  the  use  of  the  timer.  The  DIGCLOCK  program,  shown  in  Figure  5-8,  creates 
a  popup  window  that  positions  itself  in  the  lower  right  corner  of  the  display  in  the  icon 
area.  The  program  displays  the  day  of  the  week,  the  time,  and  the  date.  (See  Figure  5-9  on 
page  204.) 
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DIGCLOCK.MAK 

# 

#  DIGCLOCK.MAK  make  file 

# 


digclock.exe  :  digclock.obj  digclock.def 

$(WINLINK)  digclock,  digclock,  NUL.  KWINLIB) ,  digclock 
rc  -t  digclock.exe 

digclock.obj  :  digclock.c 
KWINCC)  digclock.c 


DIGCLOCK.C 

/* . . . 

DIGCLOCK.C  --  Digital  Clock  Program 

(c)  Charles  Petzold,  1992 
.  . ----*/ 


♦include  <windows.h> 

#include  <time.h> 

♦define  I D_T I M E R  1 

♦define  YEAR  (datetime->tm_year  %  100) 

♦define  MONTH  (datetime->tm_mon  +  1) 

♦define  MDAY  (datetime->tm_mday ) 

♦define  WDAY  (datetime->tm_wday) 

♦define  HOUR  (datetime->tm_hour ) 

♦define  MIN  (datetime->tm_min) 

♦define  SEC  (datetime->tm_sec) 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 
void  SizeTheWindow  (short  * ,  short  *,  short  * ,  short  *)  ; 

char  sDate  [2],  sTime  [2],  sAMPM  [2][5]  ; 
int  i Date ,  iTime  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "DigClock"  ; 

HWND  hwnd; 

MSG  msg; 

short  xStart,  yStart,  xClient,  yClient  ; 

WNDCLASS  wndclass  ; 


Figure  5-8.  The  DIGCLOCK  program. 


(continued) 
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if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. IpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. IpszMenuName 
wndclass. 1 pszCl assName 


=  CS_HREDRAW  !  CS.VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL.  IDC_ARR0W)  ; 
=  GetStockObject  (WHITE_BRUSH)  ; 
=  NULL  ; 

=  szAppName  ; 


RegisterClass  Uwndclass)  ; 

} 


SizeTheWindow  (&xStart,  SyStart,  &xClient,  &yClient)  ; 

hwnd  =  CreateWindow  (szAppName,  szAppName. 

WS_P0PUP  !  WS_DLGFRAME  !  WS.SYSMENU, 
xStart.  yStart, 
xClient,  yClient. 

NULL.  NULL,  hlnstance.  NULL)  ; 


if  ( ISetTimer  (hwnd.  I D_T I M E R ,  1000,  NULL)) 

{ 

MessageBox  (hwnd,  "Too  many  clocks  or  timers!".  szAppName. 

MB_I CON EXC LAMAT ION  !  MB_0K)  ; 
return  FALSE  ; 

} 

ShowWindow  (hwnd,  SW.SHOWNOACTIVATE)  ; 

UpdateWindow  (hwnd); 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam; 

} 

void  SizeTheWindow  (short  *pxStart,  short  *pyStart, 
short  *pxClient,  short  *pyClient) 

{ 

HDC  hdc  ; 

TEXTMETRIC  tm  ; 


hdc  =  CreateIC  ("DISPLAY",  NULL,  NULL.  NULL)  ; 
GetTextMetrics  (hdc,  &tm)  ; 

DeleteDC  (hdc)  ; 


(continued) 
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*pxClient  =  2  *  GetSystemMetrics  (SM_CXDLGFRAME)  +  16  *  tm.tmAveCharWidth  ; 

*pxStart  =  GetSystemMetrics  (SM_CXSCREEN)  -  *pxClient  ; 

*pyClient  =  2  *  GetSystemMetrics  (SM_CYDLGFRAME)  +  2  *  tm.tmHeight  ; 

*pyStart  =  GetSystemMetrics  (SM_CYSCREEN)  -  *pyClient  ; 

} 

void  Setlnternational  (void) 

{ 

static  char  cName  []  =  "inti"  ; 

i Date  =  GetProfilelnt  (cName,  "iDate",  0)  ; 
iTime  =  GetProfilelnt  (cName,  "iTime",  0)  ; 

GetProfileString  (cName,  "sDate",  "/",  sDate,  2)  ; 

GetProf i 1 eStri ng  (cName,  "sTime",  sTime,  2)  ; 

GetProfileString  (cName,  "sll59",  "AM",  sAMPM  [0],  5)  ; 

GetProfileString  (cName,  "s2359",  "PM",  sAMPM  [1],  5)  ; 

} 

void  WndPaint  (HWND  hwnd,  HDC  hdc) 

{ 

static  char  szWday[]  =  "Sun\Mon\Tue\Wed\Thu\Fri\Sat"  ; 
char  cBuf f er[40]  ; 

long  ITime  ; 

RECT  rect  ; 

short  nLength  ; 

struct  tm  *datetime  ; 

time  (&lTime)  ; 

datetime  =  localtime  (&lTime)  ; 

nLength  =  wsprintf  (cBuffer,  "  %s  %d%s%02d%s%02d  \r\n", 

( LPSTR)  szWday  +  4  *  WDAY , 

iDate  ==  1  ?  MDAY  :  iDate  ==  2  ?  YEAR  :  MONTH,  (LPSTR)  sDate, 

iDate  ==  1  ?  MONTH  :  iDate  ==  2  ?  MONTH  :  MDAY,  (LPSTR)  sDate, 

iDate  ==  1  ?  YEAR  :  iDate  ==  2  ?  MDAY  :  YEAR)  ; 

if  (iTime  ==  1) 

nLength  +=  wsprintf  (cBuffer  +  nLength,  "  %02d%s%02d%s%02d  ", 

HOUR,  (LPSTR)  sTime,  MIN,  (LPSTR)  sTime,  SEC)  ; 

else 

nLength  +=  wsprintf  (cBuffer  +  nLength,  "  %d%s%02d%s%02d  %s  ", 

(HOUR  %  12)  ?  (HOUR  %  12)  :  12, 

(LPSTR)  sTime,  MIN.  (LPSTR)  sTime,  SEC, 

(LPSTR)  sAMPM  [HOUR  /  12])  ; 

GetClientRect  (hwnd,  &rect)  ; 

DrawText  (hdc,  cBuffer,  -1,  &rect,  DT_C ENTER  !  DOOCLIP)  ; 

} 


(continued) 
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long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  1 Param) 

{ 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

switch  (message) 

{ 

case  WM_C REATE  : 

Setlnternational  0  ; 
return  0  ; 

case  WM.TIMER  : 

Inval idateRect  (hwnd,  NULL,  FALSE)  ; 
return  0  ; 

case  WM.PAINT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

WndPaint  (hwnd,  hdc)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_W ININICHANGE  : 

Setlnternational  ()  ; 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

case  WM.DESTROY  : 

KillTimer  (hwnd,  ID.TIMER)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  1 Param)  ; 

} 


DIGCLOCK.DEF 


DIGCLOCK.DEF  module  definition  file 


NAME  DIGCLOCK 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Digital  Clock  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 
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Figure  5-9.  The  DIGCLOCK  window. 

All  the  programs  shown  so  far  have  used  the  window  style  WS_OVERLAPPEDWINDOW 
as  the  third  parameter  to  the  CreateWindow  function.  DIGCLOCK  uses  the  window  style: 

WS.POPUP  !  WS.DLGFRAME  !  WS.SYSMENU 

This  creates  a  style  of  window  known  as  “popup,”  with  a  dialog  box  frame  and  a  system 
menu.  The  popup  style  is  most  commonly  used  for  dialog  boxes  and  message  boxes,  and 
only  rarely  for  applications.  DIGCLOCK  also  uses  yet  another  variation  of  the  ShowWindow 
call: 


ShowWindow  (hwnd,  SW_SH0WN0ACT I VATE )  ; 

Normally,  a  program  becomes  the  active  window  when  you  run  it.  SW_SHOWNOACTI- 
VATE  tells  Windows  that  the  program  that  loaded  DIGCLOCK  should  remain  the  active 
window.  You  can  make  DIGCLOCK  active,  however,  by  clicking  on  its  window  with  the 
mouse  or  by  pressing  Alt-Tab  or  Alt-Esc.  Although  DIGCLOCK  has  no  system  menu  box, 
you  can  still  access  the  system  menu  when  DIGCLOCK  is  active  by  pressing  Alt-Spacebar. 
If  you  select  Move,  you  can  move  the  window  with  the  keyboard. 

Positioning  and  Sizing  the  Popup 

The  DIGCLOCK  popup  window  is  positioned  at  the  lower  right  corner  of  the  display.  The 
window  must  be  large  enough  to  accommodate  two  lines  of  text  of  16  characters  each.  The 
SizeTheWindow  procedure  in  DIGCLOCK.C  determines  the  correct  parameters  to  use  in 
the  CreateWindow  call.  Normally,  a  program  cannot  obtain  a  text  size  without  first  creating 
a  window  because  it  needs  the  window  handle  to  obtain  a  device  context  handle.  DIGCLOCK 
gets  around  this  problem  by  obtaining  an  information  device  context  handle  for  the  screen 
using  CreatelC.  This  function  is  similar  to  CreateDC  (used  in  the  BLOWUP  program  in 
Chapter  4)  but  is  used  to  obtain  information  from  the  device  context.  The  text  size  in  com¬ 
bination  with  information  available  from  GetSystemMetrics  is  enough  to  derive  an  initial 
starting  position  and  window  size. 

Getting  the  Date  and  Time 

In  its  WndPaint  function,  DIGCLOCK  uses  the  time  and  localtime  C  functions  to  deter¬ 
mine  the  current  date  and  time.  The  localtime  function  puts  all  the  information  we  need 
into  a  structure;  several  macro  definitions  near  the  top  of  the  program  help  make  the 
wsprintfc alls  more  readable.  (You  should  avoid  making  MS-DOS  or  ROM  BIOS  function 
calls  in  your  Windows  programs;  use  Windows  functions  or  the  C  run  time  library  instead.) 
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Going  International 

Windows  includes  international  support.  The  WIN. INI  file  created  during  installation  of 
Windows  contains  a  section  headed  [inti].  This  lists  information  concerning  formats  of 
dates,  time,  currency,  and  numbers.  You  can  display  dates  in  one  of  three  different  formats: 
month-day-year,  year-month-day,  or  day-month-year.  The  separator  between  these  three 
numbers  can  be  a  slash,  a  dash,  a  period,  or,  in  fact,  any  character  you  like.  You  can  display 
the  time  in  either  12-hour  or  24-hour  format;  a  colon  or  a  period  is  commonly  used  to  sepa¬ 
rate  hours,  minutes,  and  seconds. 

The  Setlnternational  function  in  DIGCLOCK  retrieves  this  formatting  information 
from  the  WIN.INI  file  by  using  the  Windows  GetProfilelnt  (for  integers)  and  Get- 
ProfileString  (for  strings).  These  calls  must  include  default  values  if  Windows  cannot  find 
the  values  in  WIN.INI.  Setlnternational  stores  the  values  in  global  variables  that  have  the 
same  names  as  the  text  strings  that  identify  them  in  WIN.INI.  The  WndPaint function  uses 
the  values  obtained  from  WIN.INI  to  format  the  date  and  time  displays  and  then  calls 
DrawText  to  center  the  two  lines  of  text  within  the  window. 

As  you  would  expect,  whenever  DIGCLOCK’s  window  procedure  receives  a 
WM-TIMER  message,  it  invalidates  the  window  to  generate  a  WM_PAINT  message.  But 
WndProc  also  invalidates  the  window  when  it  receives  a  WM_WININICHANGE  message. 
Any  application  that  changes  WIN.INI  sends  the  WM_WININICHANGE  message  to  all  ac¬ 
tive  Windows  applications.  If  the  [inti]  section  of  WIN.INI  is  changed,  DIGCLOCK  will 
know  and  will  obtain  the  new  international  information.  To  see  how  this  works,  load 
DIGCLOCK,  load  the  CONTROL  PANEL  program  included  with  Windows,  select  the  Inter¬ 
national  icon,  and  change  either  the  date  format,  the  date  separator,  the  time  format,  or  the 
time  separator.  Now  press  Enter.  The  Control  Panel  updates  the  WIN.INI  file,  and 
DIGCLOCK’s  display  reflects  that  change — Windows’  message  magic  at  work. 

When  the  window  procedure  receives  a  WM_WININICHANGE  message,  it  invali¬ 
dates  the  window  using: 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 

When  DIGCLOCK  receives  a  WM_TIMER  message,  it  invalidates  the  window  using: 

InvalidateRect  (hwnd,  NULL,  FALSE)  ; 

A  value  of  TRUE  in  the  last  parameter  tells  Windows  to  erase  the  background  before  draw¬ 
ing  the  window.  A  value  of  FALSE  tells  Windows  simply  to  draw  over  the  existing  back¬ 
ground.  We  use  FALSE  when  processing  WM -TIMER  messages  because  this  approach 
reduces  flickering  of  the  display.  You  may  be  wondering  why  we  need  to  use  the  TRUE 
value  at  all. 

A  TRUE  value  is  necessary  when  processing  WM_WININICHANGE  messages  be¬ 
cause  the  length  of  the  displayed  strings  can  change  by  several  characters  if  you  switch  the 
time  format  from  12  hours  to  24  hours.  However,  the  largest  change  that  occurs  as  a  result  of 
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a  WM_TIMER  message  is  two  characters — for  instance,  when  the  date  advances  from 
12/31/87  to  1/1/88 — and  the  formatted  string  that  WndPaint  uses  for  the  display  has  a  cou¬ 
ple  of  blanks  on  each  end  to  account  for  this  change  in  length  and  the  proportional  font. 

We  could  also  have  DIGCLOCK  process  WM_TIMECHANGE  messages,  which  notify 
applications  of  changes  to  the  system  date  or  time.  Because  DIGCLOCK  is  updated  every 
second  by  WM_TIMER  messages,  this  is  unnecessary.  Processing  WM_TIMECHANGE 
messages  would  make  more  sense  for  a  clock  that  was  updated  every  minute. 

WINDOWS  STANDARD  TIME 

If  you’ve  been  scouting  around  the  Windows  Programmer’s  Reference,  you  may  be  won¬ 
dering  why  the  Windows  GetCurrentTime  function  is  not  used  in  DIGCLOCK.  The  answer 
is  that  GetCurrentTime  tells  you  about  “Windows  time”  rather  than  real  time.  This  is  the 
time  (in  milliseconds)  since  the  beginning  of  the  current  Windows  session.  GetCurrent¬ 
Time  is  used  mostly  for  calculating  a  difference  from  the  time  returned  from  Get- 
MessageTime.  You  can  use  these  two  calls  while  processing  a  message  to  determine  how 
long  the  message  was  in  the  message  queue  before  you  retrieved  it  for  processing. 
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Child  Window 
Controls 


Chapter  4  showed  programs  in  the  CHECKER  series  that  display  a  grid  of  rectangles.  When 
you  click  the  mouse  in  a  rectangle,  the  program  draws  an  X.  When  you  click  again,  the  X 
disappears.  As  you  played  with  the  program,  you  may  have  thought  that  the  rectangle  with 
the  X  inside  looked  vaguely  familiar.  If  the  rectangle  were  reduced  in  size,  it  would  resem¬ 
ble  a  “check  box”  that  Windows  programs  use  in  dialog  boxes  to  allow  the  selection  of 
options. 

Although  the  CHECKER1  and  CHECKER2  versions  of  this  program  use  only  one  main 
window,  the  CHECKER3  version  uses  a  child  window  for  each  rectangle.  The  rectangles 
are  maintained  by  a  separate  window  procedure  called  ChildWndProc.  If  we  wanted  to, 
we  could  add  a  facility  to  ChildWndProc  to  send  a  message  to  its  parent  window  procedure 
( WndProc )  whenever  a  rectangle  is  checked  or  unchecked. 

Here’s  how:  The  child  window  procedure  can  determine  the  window  handle  of  its 
parent  by  calling  GetParent\ 

hwndParent  =  GetParent  (hwnd)  ; 

where  hwnd  is  the  window  handle  of  the  child  window.  It  can  then  send  a  message  to  the 
parent  window  procedure: 

SendMessage  (hwndParent,  message,  wParam,  1  Pa  ram)  ; 

Perhaps  for  this  message  the  child  window  could  set  wParam  to  its  child  window  ID.  The 
iParam  could  be  set  to  a  1  if  the  child  window  were  being  checked  and  a  0  if  it  were  being 
unchecked. 
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This  in  effect  creates  a  “child  window  control.”  The  child  window  processes  mouse 
and  keyboard  messages  and  notifies  the  parent  window  when  the  child  window’s  state  has 
changed.  In  this  way,  the  child  window  becomes  an  input  device  for  the  parent  window. 

Although  you  can  create  your  own  child  window  controls,  you  can  also  take  advan¬ 
tage  of  several  predefined  window  classes  (and  window  procedures)  that  your  program 
can  use  to  create  child  window  controls.  These  controls  take  the  form  of  buttons,  check 
boxes,  edit  boxes,  list  boxes,  combo  boxes,  text  strings,  and  scroll  bars.  For  instance,  if  you 
want  to  put  a  button  labeled  “Recalculate”  in  a  corner  of  your  spreadsheet  program,  you 
can  create  it  with  a  single  CreateWindow  call.  You  don’t  have  to  worry  about  the  mouse 
logic  or  button  painting  logic  or  about  making  the  button  “flash”  when  it’s  clicked.  That’s 
all  done  in  Windows.  All  you  have  to  do  is  trap  WM-COMMAND  messages — that’s  how 
the  button  informs  your  window  procedure  when  it  has  been  triggered. 

Is  it  really  that  simple?  Well,  almost. 

Child  window  controls  are  used  most  often  in  dialog  boxes.  As  you’ll  see  in  Chapter 
10,  the  position  and  size  of  the  child  window  controls  are  defined  in  a  dialog  box  template 
contained  in  the  program’s  resource  script.  However,  you  can  also  use  predefined  child 
window  controls  on  the  surface  of  a  normal  window’s  client  area.  You  create  each  child 
window  with  a  CreateWindow  call  and  adjust  the  position  and  size  of  the  child  windows 
with  calls  to  MoveWindow.  The  parent  window  procedure  sends  messages  to  the  child 
window  controls,  and  the  child  window  controls  send  messages  back  to  the  parent  window 
procedure. 

When  you  bring  up  your  normal  window,  you  first  define  a  window  class  and  register 
it  with  Windows  using  RegisterClass.  You  then  create  the  window  based  on  that  class  using 
CreateWindow.  When  you  use  one  of  the  predefined  controls,  however,  you  do  not  register 
a  window  class  for  the  child  window.  The  class  already  exists  within  Windows  and  has  one 
of  these  names:  “button,”  “static,”  “scrollbar,”  “edit,”  “listbox,”  or  “combobox.”  You  simply 
use  the  name  as  the  window  class  parameter  in  CreateWindow.  The  window  style  parame¬ 
ter  to  CreateWindow  defines  more  precisely  the  appearance  and  functionality  of  the  child 
window  control.  Windows  contains  the  window  procedures  that  process  messages  to  the 
child  windows  based  on  these  classes. 

Using  child  window  controls  directly  on  the  surface  of  your  window  involves  tasks  of 
a  lower  level  than  are  required  for  using  child  window  controls  in  dialog  boxes,  where  the 
dialog  box  manager  adds  a  layer  of  insulation  between  your  program  and  the  controls 
themselves.  In  particular,  you’ll  discover  that  the  child  window  controls  you  create  on  the 
surface  of  your  window  have  no  built-in  facility  to  move  the  input  focus  from  one  control  to 
another  using  the  Tab  or  cursor  movement  keys.  A  child  window  control  can  obtain  the  in¬ 
put  focus,  but  once  it  does,  it  won’t  relinquish  the  input  focus  back  to  the  parent  window. 
This  is  a  problem  we’ll  struggle  with  throughout  this  chapter. 
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THE  BUTTON  CLASS 

We’ll  begin  our  exploration  of  the  button  window  class  with  a  program  called  BTNLOOK 
(“button  look”),  which  is  shown  in  Figure  6-1.  BTNLOOK  creates  10  child  window  button 
controls,  one  for  each  of  the  10  styles  of  buttons. 


BTNLOOK.MAK 

#— 

#  BTNLOOK.MAK  make  file 

# 

btnlook.exe  :  btnlook.obj  btnlook.def 

$(WINLINK)  btnlook,  btnlook,  NUL,  $(WINLIB),  btnlook 
rc  -t  btnlook.exe 

btnlook.obj  :  btnlook. c 
$ ( W I NCC )  btnlook. c 


BTNLOOK.C 


/*- . 

BTNLOOK.C  --  Button  Look  Program 

(c)  Charles  Petzold,  1992 
. */ 


#include  <windows.h> 


struct 

{ 

long  style  ; 
char  *text  ; 

} 

button [ ]  = 

{ 

BS_PUSHBUTTON , 
BS_DE  FPUSHBUTTON , 
BS_CH  ECKBOX , 
BS_AUTOCHECKBOX , 
BS_RAD I OBUTTON , 
BS_3STATE, 
BS_AUT03STATE, 
BS_GR0U  PBOX , 


"PUSHBUTTON", 

"DEFPUSHBUTTON", 

"CHECKBOX", 

"AUTOCHECKBOX", 

"RADIOBUTTON", 

"3STATE", 

"AUT03STATE", 

"GROUPBOX", 


Figure  6-1 .  The  BTNLOOK  program. 


(continued) 
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BS_AUT0RADI0BUTT0N .  "AUTORADIO" , 
BS.OWNERDRAW,  "OWNERDRAW" 

}  ; 

#define  NUM  (sizeof  button  /  sizeof  button  [0]) 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "BtnLook”  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbrBackg round 
wndclass. 1 pszMenuName 
wndclass. IpszClassName 


CS.HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  IDI.APPLICATION)  ; 
LoadCursor  (NULL,  IDC.ARROW)  ; 
GetStockObject  (WHITE.BRUSH)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "Button  Look", 

WS_0V  ERLAPPEDW I NDOW , 

CWJJSEDEFAULT,  CWJJSEDEFAULT, 

CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 
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{ 

static  char  szTop  []  =  "message  wParam  IParam", 

szUnd  []  =  " _  _  _ 

szFormat  []  =  "%-16s%6X%8X-%04X". 
szBuffer  [50]  ; 

static  HWND  hwndButton  [NUM]  ; 

static  RECT  rect  ; 

static  int  cxChar.  cyChar  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 
int  i  ; 

TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

GetTextMetrics  (hdc,  &tm)  ; 

cxChar  =  tm.tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm.tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 

for  (i  =  0  ;  i  <  NUM  ;  i++) 

hwndButton  [i]  =  CreateWindow  ("button",  button[i] .text, 
WS.CHILD  !  WS_V I SI BLE  !  button [i ]. styl e , 
cxChar,  cyChar  *  (1  +  2  *  i), 

20  *  cxChar,  7  *  cyChar  /  4, 
hwnd,  i, 

( ( LPCREATESTRUCT)  IParam)  ->  hlnstance,  NULL)  ; 

return  0  ; 

case  WM_SIZE  : 

rect. left  =  24  *  cxChar  ; 

rect. top  =  2  *  cyChar  ; 

rect. right  =  LOWORD  (IParam)  ; 
rect. bottom  =  HIWORD  (IParam)  ; 
return  0  ; 

case  WM_PAI NT  : 

InvalidateRect  (hwnd,  &rect,  TRUE)  ; 
hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

SetBkMode  (hdc,  TRANSPARENT)  ; 

TextOut  (hdc,  24  *  cxChar,  cyChar,  szTop,  sizeof  szTop  -  1)  ; 

TextOut  (hdc,  24  *  cxChar,  cyChar.  szUnd,  sizeof  szUnd  -  1)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

(continued) 
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case  WM.COMMAND  : 
case  WM_D RAW ITEM  : 

ScrollWindow  (hwnd,  0,  -cyChar,  &rect,  &rect)  ; 
hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc,  GetStockObject  ( SYSTEM__FI XED_F0NT) )  ; 

TextOut  (hdc.  24  *  cxChar,  cyChar  *  (rect. bottom  /  cyChar  -  1), 
szBuffer, 

wsprintf  (szBuffer,  szFormat,  (LPSTR) 

(message  ==  WM_COMMAND  ?  "WM-COMMAND"  :  "WM_DRAWITEM") , 
wParam,  HIWORD  (IParam),  LOWORD  (IParam)))  ; 

ReleaseDC  (hwnd,  hdc)  ; 

ValidateRect  (hwnd,  NULL)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


BTNLOOK.DEF 


BTNLOOK.DEF  module  definition  file 


NAME  BTNLOOK 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Button  Look  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

' WI NSTUB . EXE ' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


As  you  click  on  each  button,  it  sends  a  WM -COMMAND  message  to  the  parent 
window  procedure,  which  is  the  familiar  WndProc.  BTNLOOK’s  WndProc  displays  the 
wParam  and  IParam  parameters  of  this  message  on  the  right  half  of  the  client  area, 
as  shown  in  Figure  6-2. 

You  won’t  see  the  button  with  the  style  BS-OWNERDRAW  on  this  window  because 
this  is  a  style  of  button  that  the  program  is  responsible  for  drawing.  The  button  indicates  it 
needs  drawing  by  WM-DRAWITEM  messages  containing  an  IParam  message  parameter 
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n 

Button  Look 

mm 

messaqe 
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IParam 
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Figure  6-2.  The  BTNLOOK  display. 

that  is  a  pointer  to  a  structure  of  type  DRAWITEMSTRUCT.  I’ll  discuss  owner-draw  buttons 
in  more  detail  later  in  this  chapter. 


Creating  the  Child  Windows 

BTNLOOK  defines  a  structure  called  button  that  contains  button  window  styles  and  des¬ 
criptive  text  strings  for  each  of  the  10  types  of  buttons.  The  button  window  styles  all  begin 
with  the  letters  BS,  which  stand  for  “button  style.” 

The  10  button  child  windows  are  created  in  a  for  loop  during  WM -CREATE  message 
processing  in  WndProc.  The  CreateWindow call  uses  the  following  parameters: 


Class  name 

"button" 

Window  text 

button[i].text 

Window  style 

WS-CHILD  !  WS-VISIBLE  1  button[i]. style 

x  position 

cxChar 

y  position 

cyChar  *  (1  +  2  *  i) 

Width 

20  *  xChar 

Height 

7  *  yChar  /  4 

Parent  window 

hwnd 

Child  window  ID 

i 

Instance  handle 

((LPCREATESTRUCT)  IParam)  ->  hlnstance 

Extra  parameters 

NULL 
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The  class  name  parameter  is  the  predefined  name.  The  window  style  uses  WS-CHILD, 
WS-VISIBLE,  and  one  of  the  ten  button  styles  (BS-PUSHBUTTON,  BS-DEFPUSHBUTTON, 
and  so  forth)  in  the  button  structure.  The  window  text  parameter  (which  for  a  normal  win¬ 
dow  is  the  text  that  appears  in  the  caption  bar)  is  text  that  will  be  displayed  with  each  button. 
I’ve  simply  used  text  that  identifies  the  button  style. 

The  jc  position  and  y  position  parameters  indicate  the  placement  of  the  upper  left  cor¬ 
ner  of  the  child  window  relative  to  the  upper  left  corner  of  the  parent  window’s  client  area. 
The  width  and  height  parameters  specify  the  width  and  height  of  each  child  window. 

The  child  window  ID  parameter  should  be  unique  for  each  child  window.  This  ID 
helps  your  window  procedure  identify  the  child  window  when  processing  WM -COM¬ 
MAND  messages  from  it. 

The  instance  handle  parameter  of  the  CreateWindou)  call  looks  a  little  strange,  but 
we’re  taking  advantage  of  the  fact  that  during  a  WM-CREATE  message  IParam  is  actually  a 
pointer  to  a  structure  of  type  CREATESTRUCT  (“creation  structure”)  that  has  a  member 
hlnstance.  So  we  cast  IParam  into  a  long  (or  far)  pointer  to  a  CREATESTRUCT  structure 
and  get  hlnstance  out. 

(Some  Windows  programs  use  a  global  variable  named  hlnst  to  give  window  pro¬ 
cedures  access  to  the  instance  handle  available  in  WinMain.  In  WinMain ,  you  need  simply 
set: 


hlnst  =  hlnstance  ; 

before  creating  the  main  window.  In  Chapter  4  we  used  GetWindowWord  to  obtain  the 
instance  handle: 

GetWindowWord  (hwnd,  GWW_H INSTANCE) 

Any  of  these  methods  is  fine.) 

After  the  CreateWindou)  call,  we  don’t  have  to  do  anything  more  with  these  child 
windows.  The  button  window  procedure  within  Windows  maintains  them  for  us  and 
handles  all  repainting  jobs.  (The  exception  is  the  button  with  the  BS-OWNERDRAW  style; 
as  I’ll  discuss  later,  this  button  style  requires  the  program  to  draw  the  button.)  At  the  pro¬ 
gram’s  termination,  Windows  destroys  these  child  windows  when  the  parent  window  is 
destroyed. 

The  Child  Talks  to  Its  Parent 

When  you  run  BTNLOOK,  you  see  the  different  button  types  displayed  on  the  left  side  of  the 
client  area.  (The  BS_OWNERDRAW  button  is  not  visible.)  As  I  mentioned  earlier,  when  you 
click  a  button  with  the  mouse,  the  child  window  control  sends  a  WM -COMMAND  message 
to  its  parent  window.  BTNLOOK  traps  the  WM-COMMAND  message  and  displays  the 
values  of  wParam  and  IParam.  Here’s  what  they  mean: 
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wParam  Child  window  ID 

LOWORD  ( IParam )  Child  window  handle 

HIWORD  ( IParam )  Notification  code 

The  child  window  ID  is  the  value  passed  to  CreateWindow  when  the  child  window  is 
created.  In  BTNLOOK  these  IDs  are  0  through  9  for  the  10  buttons  displayed  in  the  client 
area.  The  child  window  handle  is  the  value  that  Windows  returns  from  the  CreateWindow 
call. 

The  notification  code  is  a  submessage  code  that  the  child  window  uses  to  tell  the 
parent  window  in  more  detail  what  the  message  means.  The  possible  values  of  button 
notification  codes  are  defined  in  WINDOWS. H: 


Button  Notification 

Code  Identifier 

Value 

BN-CLICKED 

0 

BN-PAINT 

1 

BN-HILITE 

2 

BN-UNHILITE 

3 

BN-DISABLE 

4 

BN-DOUBLECLICKED 

5 

The  notification  codes  1  through  5  are  for  an  obsolete  button  style  called  BS_USER- 
BUTTON. 

You’ll  notice  that  when  you  click  a  button  with  the  mouse,  a  dashed  line  surrounds 
the  text  of  the  button.  This  indicates  that  the  button  has  the  input  focus.  All  keyboard  input 
now  goes  to  the  child  window  button  control  rather  than  to  the  main  window.  However, 
when  the  button  control  has  the  input  focus,  it  ignores  all  keystrokes  except  the  Spacebar, 
which  now  has  the  same  effect  as  a  mouse  click. 


The  Parent  Talks  to  Its  Child 


Although  BTNLOOK  does  not  demonstrate  this  fact,  a  window  procedure  can  also  send 
messages  to  the  child  window  control.  Five  button-specific  messages  are  defined  in  WIN- 
DOWS.H;  each  begins  with  the  letters  “BM,”  which  stand  for  “button  message.”  These 
messages  are  defined  in  WINDOWS. H  in  terms  of  the  WM_USER  identifier: 


#define  BM.GETCHECK 
//define  BM_SETCHECK 
//define  BM_GETSTATE 
//define  BM_S ETSTATE 
//define  BM_SETSTYLE 


(WMJJSER+0) 
( WM_USER+1 ) 
(WMJJSER+2) 
(WM.USER+3) 
(WM.USER+4) 
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The  WM-USER  identifier  is  available  for  programs  to  define  their  own  messages  beyond 
the  predefined  messages.  Each  window  class  can  have  its  own  separate  set  of  messages 
unique  to  that  class.  The  other  classes  of  predefined  child  window  controls  also  can  have 
their  own  messages  defined  in  terms  of  WM -USER. 

The  BM-GETCHECK  and  BM-SETCHECK  messages  are  sent  by  a  parent  window  to 
a  child  window  control  to  get  and  set  the  check  mark  of  check  boxes  and  radio  buttons. 
The  BM-GETSTATE  and  BM-SETSTATE  messages  refer  to  the  normal  or  “pushed”  state  of 
a  window  when  you  click  it  with  the  mouse  or  press  it  with  the  Spacebar.  We’ll  see  how 
these  messages  work  when  we  look  at  each  type  of  button.  The  BM-SETSTYLE  message 
lets  you  change  the  button  style  after  the  button  is  created. 

Push  Buttons 

The  first  two  buttons  shown  in  BTNLOOK  are  “push”  buttons.  A  push  button  is  a  rectangle 
enclosing  text  specified  in  the  window  text  parameter  of  the  CreateWindow  call.  The  rect¬ 
angle  takes  up  the  full  height  and  width  of  the  dimensions  given  in  the  CreateWindow  or 
MoveWindow  call.  The  text  is  centered  within  the  rectangle. 

Push-button  controls  are  used  mostly  to  trigger  an  immediate  action  without  retain¬ 
ing  any  type  of  on/off  indication.  The  two  types  of  push-button  controls  have  window 
styles  called  BS-PUSHBUTTON  and  BS-DEFPUSHBUTTON.  The  “DEF”  in  BS-DEFPUSH- 
BUTTON  stands  for  “default.”  When  used  to  design  dialog  boxes,  BS_PUSHBUTTON  con¬ 
trols  and  BS_DEFPUSHBUTTON  controls  function  differently  from  one  another.  When 
used  as  child  window  controls,  however,  the  two  types  of  push  buttons  function  the  same 
way,  although  BS_DEFPUSHBUTTON  has  a  heavier  outline. 

A  push  button  looks  best  when  its  height  is  1A  times  the  height  of  a  SYSTEM -FONT 
character,  which  is  what  BTNLOOK  uses.  The  push  button’s  width  must  accommodate  at 
least  the  width  of  the  text  plus  two  additional  characters. 

When  the  mouse  cursor  is  inside  the  push  button,  pressing  the  mouse  button  causes 
the  button  to  repaint  itself  using  3D-style  shading  to  appear  as  if  it’s  been  depressed. 
Releasing  the  mouse  button  restores  the  original  appearance  and  sends  a  WM -COM¬ 
MAND  message  to  the  parent  window  with  notification  code  BN-CLICKED.  As  with  the 
other  button  types,  when  a  push  button  has  the  input  focus,  a  dashed  line  surrounds  the 
text,  and  pressing  and  releasing  the  Spacebar  has  the  same  effect  as  pressing  and  releasing 
the  mouse  button. 

You  can  simulate  a  push-button  flash  by  sending  the  window  a  BM_SETSTATE  mes¬ 
sage.  This  causes  the  button  to  be  depressed: 

SendMessage  (hwndButton,  BM_SETSTATE,  1,  0L)  ; 

This  call  causes  the  button  to  return  to  normal: 

SendMessage  (hwndButton,  BM.SETSTATE,  0,  0L)  ; 

The  hwndButton  window  handle  is  the  value  returned  from  the  CreateWindow  call. 
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You  can  also  send  a  BM-GETSTATE  message  to  a  push  button.  The  child  window 
control  returns  the  current  state  of  the  button — TRUE  if  the  button  is  depressed  and  FALSE 
(or  0)  if  normal.  Most  applications  do  not  require  this  information,  however.  And  because 
push  buttons  do  not  retain  any  on/off  information,  the  BM_SETCHECK  and  BM_GET- 
CHECK  messages  are  not  used. 

Check  Boxes 

A  check  box  is  a  square  box  with  text;  the  text  usually  appears  to  the  right  of  the  check 
box.  (If  you  include  the  BS-LEFTTEXT  style  when  creating  the  button,  the  text  appears  to 
the  left.)  Check  boxes  are  usually  incorporated  in  an  application  to  allow  a  user  to  select 
options.  The  check  box  commonly  functions  as  a  toggle  switch:  Clicking  the  box  once 
causes  an  X  to  appear;  clicking  again  toggles  the  X  off. 

The  two  most  common  styles  for  a  check  box  are  BS_CHECKBOX  and  BS-AUTO- 
CHECKBOX.  When  you  use  the  BS_CHECKBOX  style,  you  must  set  the  X  mark  yourself  by 
sending  the  control  a  BM_SETCHECK  message.  The  wParam  parameter  is  set  to  1  to  create 
an  X  and  to  0  to  remove  it.  You  can  obtain  the  current  check  state  of  the  box  by  sending  the 
control  a  BM_GETCHECK  message.  You  might  use  code  like  this  to  toggle  the  X  mark 
when  processing  a  WM_COMMAND  message  from  the  control: 

SendMessage  (LOWORD  (IParam).  BM_S ETCH ECK ,  (WORD) 

ISendMessage  (LOWORD  (IParam),  BM.GETCHECK,  0,  0L),  0L)  ; 

Note  the  /operator  in  front  of  the  second  SendMessage  c all.  The  low  word  of  IParam  is  the 
child  window  handle  passed  to  your  window  procedure  in  the  WM-COMMAND  message. 
When  you  later  need  to  know  the  state  of  the  button,  send  it  another  BM_GETCHECK 
message.  Or  you  can  retain  the  current  check  state  in  a  static  variable  in  your  window  pro¬ 
cedure.  You  can  also  initialize  a  BS_CHECKBOX  check  box  with  an  X  by  sending  it  a 
BM_SETCHECK  message: 

SendMessage  (hwndButton,  BM.SETCHECK,  1,  0L)  ; 

For  the  BS_AUTOCHECKBOX  style,  the  button  control  itself  toggles  the  X  on  and  off. 
Your  window  procedure  can  ignore  WM -COMMAND  messages.  When  you  need  the 
current  state  of  the  button,  send  the  control  a  BM-GETCHECK  message: 

nCheck  =  (WORD)  SendMessage  (hwndButton,  BM_GETCHECK,  0,  0L)  ; 

The  value  of  nCheck  is  TRUE  or  nonzero  if  the  button  is  checked,  FALSE  or  0  if  not. 

The  other  two  check  box  styles  are  BS-3STATE  and  BS-AUT03STATE.  As  their 
names  indicate,  these  styles  can  display  a  third  state  as  well — a  gray  color  within  the  check 
box — which  occurs  when  you  send  the  control  a  WM-SETCHECK  message  with  wParam 
equal  to  2.  The  gray  color  indicates  to  the  user  that  the  box  cannot  be  checked —  that  is,  that 
it’s  disabled.  However,  the  check  box  control  continues  to  send  messages  to  the  parent 
when  the  box  is  clicked.  Better  methods  for  disabling  a  check  box  are  described  later. 
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The  check  box  is  aligned  with  the  rectangle’s  left  edge  and  is  centered  within  the  top 
and  bottom  dimensions  of  the  rectangle  that  were  specified  during  the  CreateWindow c all. 
Clicking  anywhere  within  the  rectangle  causes  a  WM_COMMAND  message  to  be  sent  to 
the  parent.  The  minimum  height  for  a  check  box  is  one  character  height.  The  minimum 
width  is  the  number  of  characters  in  the  text  plus  two. 

Radio  Buttons 

A  radio  button  looks  very  much  like  a  check  box  except  that  it  is  shaped  like  a  circle  rather 
than  a  box.  A  heavy  dot  within  the  circle  indicates  that  the  radio  button  has  been  checked. 
The  radio  button  has  the  window  style  BS_RADIOBUTTON  or  BS_AUTORADIOBUT- 
TON,  but  the  latter  is  used  only  in  dialog  boxes. 

In  dialog  boxes,  groups  of  radio  buttons  are  conventionally  used  to  indicate  mutually 
exclusive  options.  (For  instance,  look  at  the  dialog  box  in  the  Windows  Terminal  program 
that  appears  when  you  select  Communications  from  the  Settings  menu.)  Unlike  check 
boxes,  radio  buttons  do  not  work  as  toggles — that  is,  when  you  click  a  radio  button  a 
second  time,  its  state  remains  unchanged. 

When  you  receive  a  WM_COMMAND  message  from  a  radio  button,  you  should  dis¬ 
play  its  check  by  sending  it  a  BM_SETCHECK  message  with  wParam  equal  to  1: 

SendMessage  (hwndButton,  BM_SETCHECK,  1,  0L)  ; 

For  all  other  radio  buttons  in  the  same  group,  you  can  turn  off  the  checks  by  sending  them 
BM_SETCHECK  messages  with  wParam  equal  to  0: 

SendMessage  (hwndButton,  BM_SETCHECK,  0,  0L)  ; 

Group  Boxes 

The  group  box,  style  BS-GROUPBOX,  is  an  oddity  in  the  button  class.  It  neither  processes 
mouse  or  keyboard  input  nor  sends  WM_COMMAND  messages  to  its  parent.  The  group 
box  is  a  rectangular  outline  with  its  window  text  at  the  top.  Group  boxes  are  often  used  to 
enclose  other  button  controls. 

Changing  the  Button  Text 

You  can  change  the  text  in  a  button  (or  in  any  other  window)  by  calling  SetWindowText : 
SetWindowText  (hwnd,  IpszString)  ; 

where  hwnd  is  a  handle  to  the  window  whose  text  is  being  changed  and  IpszString  is  a 
long  (or  far)  pointer  to  a  null-terminated  string.  For  a  normal  window,  this  text  is  the  text  of 
the  caption  bar.  For  a  button  control,  it’s  the  text  displayed  with  the  button. 

You  can  also  obtain  the  current  text  of  a  window: 

nLength  =  GetWindowText  (hwnd,  IpszBuffer,  nMaxLength)  ; 


218 


Chapter  6:  Child  Window  Controls 


The  nMaxLength  parameter  specifies  the  maximum  number  of  characters  to  copy  into  the 
buffer  pointed  to  by  IpszBuffer :  The  function  returns  the  string  length  copied.  You  can 
prepare  your  program  for  a  particular  text  length  by  first  calling: 

nLength  =  GetWindowTextLength  (hwnd)  ; 

Visible  and  Enabled  Buttons 

To  receive  mouse  and  keyboard  input,  a  child  window  must  be  both  visible  (displayed)  and 
enabled.  When  a  child  window  is  visible  but  not  enabled,  Windows  displays  it  in  gray 
rather  than  black. 

If  you  do  not  include  WS  JVISIBLE  in  the  window  class  when  creating  the  child  win¬ 
dow,  the  child  window  will  not  be  displayed  until  you  make  a  call  to  ShowWindow. 

ShowWindow  (hwndChild,  SW.SHOWNORMAL)  ; 

If  you  include  WS_VISIBLE  in  the  window  class,  you  do  not  need  to  call  ShowWindow. 
However,  you  can  hide  the  child  window  by  a  call  to  ShowWindow : 

ShowWindow  (hwndChild,  SW_H IDE)  ; 

You  can  determine  if  a  child  window  is  visible  by  a  call  to: 

IsWindowVisible  (hwndChild)  ; 

You  can  also  enable  and  disable  a  child  window.  By  default,  a  window  is  enabled. 
You  can  disable  it  by  calling: 

EnableWindow  (hwndChild,  FALSE)  ; 

For  button  controls,  this  has  the  effect  of  graying  the  button  text  string.  The  button  no 
longer  responds  to  mouse  or  keyboard  input.  This  is  the  best  method  for  indicating  that  a 
button  option  is  currently  unavailable. 

You  can  reenable  a  child  window  by  calling: 

EnableWindow  (hwndChild,  TRUE)  ; 

You  can  determine  whether  a  child  window  is  enabled  by  calling: 

IsWi ndowEnabl ed  (hwndChild)  ; 

Buttons  and  Input  Focus 

As  I  noted  earlier  in  this  chapter,  push  buttons,  check  boxes,  radio  buttons,  and  owner- 
draw  buttons  receive  the  input  focus  when  they  are  clicked  with  the  mouse.  The  control 
indicates  it  has  the  input  focus  by  a  dashed  line  surrounding  the  text.  When  the  child  win¬ 
dow  control  gets  the  input  focus,  the  parent  window  loses  it;  all  keyboard  input  then  goes 
to  the  control  rather  than  to  the  parent  window.  However,  the  child  window  control 
responds  only  to  the  Spacebar,  which  now  functions  like  the  mouse.  This  situation 
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presents  an  obvious  problem:  Your  program  has  lost  control  of  keyboard  processing.  Let’s 
see  what  we  can  do  about  it. 

When  Windows  switches  the  input  focus  from  one  window  (such  as  a  parent)  to  an¬ 
other  (such  as  a  child  window  control),  it  first  sends  a  WM_KILLFOCUS  message  to  the 
window  losing  the  input  focus.  The  tuParam  parameter  is  the  handle  of  the  window  that  is 
to  receive  the  input  focus.  Windows  then  sends  a  WM_SETFOCUS  message  to  the  window 
receiving  the  input  focus,  with  wParam  the  handle  of  the  window  losing  the  input  focus. 
(In  both  cases,  wParam  may  be  NULL,  which  indicates  that  no  window  has  or  is  receiving 
the  input  focus.) 

A  parent  window  can  prevent  a  child  window  control  from  getting  the  input  focus  by 
processing  WM_KILLFOCUS  messages.  Assume  that  the  array  hwndChild  contains  the 
window  handles  of  all  child  windows.  (These  were  saved  in  the  array  during  the 
CreateWindow  calls  that  created  the  windows.)  NUM  is  the  number  of  child  windows: 

case  WM_KI LLFOCUS  : 

for  (i  =  0  ;  i  <  NUM  ;  i++) 

if  (hwndChild  [i]  ==  wParam) 

{ 

SetFocus  (hwnd)  ; 
break  ; 

} 

return  0  ; 

In  this  code,  when  the  parent  window  detects  that  it’s  losing  the  input  focus  to  one  of  its 
child  window  controls,  it  calls  SetFocus  to  restore  the  input  focus  to  itself. 

Here’s  a  simpler  (but  less  obvious)  way  of  doing  it: 

case  WM_KI LLFOCUS  : 

if  (hwnd  ==  GetParent  (wParam)) 

SetFocus  (hwnd)  ; 
return  0  ; 

Both  these  methods  have  a  shortcoming,  however:  They  prevent  the  button  from  re¬ 
sponding  to  the  Spacebar,  because  the  button  never  gets  the  input  focus.  A  better  approach 
would  be  to  let  the  button  get  the  input  focus  but  also  to  include  the  facility  for  the  user  to 
move  from  button  to  button  using  the  Tab  key.  At  first  this  sounds  impossible,  but  I’ll  show 
you  how  to  accomplish  it  with  a  technique  called  “window  subclassing”  in  the  COLORS1 
program  shown  later  in  this  chapter. 

CONTROLS  AND  COLORS 

I  deliberately  put  a  little  “gotcha”  into  BTNLOOK.  There  is  something  wrong  with  the  pro¬ 
gram.  It  may  not  be  immediately  apparent,  but  here’s  how  to  see  it:  Run  BTNLOOK  and 
bring  up  the  Control  Panel  program  included  with  Windows.  Select  the  Color  icon;  this 
brings  up  a  dialog  box  that  lets  you  change  system  colors.  Select  Color  Palette  and  change 
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the  colors  of  Window  Background  and  Window  Text,  and  save  the  new  settings  by  clicking 
the  OK  button:  The  background  and  text  of  the  buttons  (with  the  exception  of  the  push 
buttons)  in  BTNLOOK  change  to  reflect  the  new  colors,  but  the  background  color  and  text 
color  of  the  rest  of  BTNLOOK’s  client  area  remain  the  same — black  text  on  a  white  back¬ 
ground.  It  looks  dreadful. 

What  happened?  Simple — the  button  colors  change  because  they  are  based  on  the 
system  colors  you  set  in  Control  Panel,  but  BTNLOOK’s  client-area  background  remains 
white  because  white  is  specified  in  the  window  class: 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 

When  BTNLOOK  writes  text  to  the  display,  it  uses  the  text  color  and  background  color 
defined  in  the  default  device  context.  These  are  always  black  and  white,  regardless  of  the 
system  colors  set  with  Control  Panel. 

Let’s  fix  this  problem.  I  discussed  Windows’  use  of  color  in  Chapter  5,  but  this  prob¬ 
lem  involves  Windows  “system  colors.” 

System  Colors 

Windows  maintains  21  system  colors  for  painting  various  parts  of  the  display.  You  can 
obtain  and  set  these  colors  using  GetSysColor  and  SetSysColor.  Identifiers  defined  in 
WINDOWS.H  specify  the  system  color.  Setting  a  system  color  with  SetSysColor  changes  it 
only  for  the  current  Windows  session. 

You  can  change  system  colors  using  the  Windows  Control  Panel  program  or  by 
modifying  the  [colors]  section  in  the  WIN. INI  file.  The  [colors]  section  uses  keywords  for 
the  21  system  colors  (different  from  the  GetSysColor  and  SetSysColor  identifiers)  followed 
by  red,  green,  and  blue  values  that  can  range  from  0  to  255.  The  following  table  shows  how 
the  21  system  colors  are  identified  using  the  WINDOWS.H  identifiers  for  GetSysColor  and 
SetSysColor ;  the  WIN.INI  keywords,  and  the  Control  Panel  terms: 


GetSysColor  &  SetSysColor 

WIN.INI 

Control  Panel 

COLOR-SCROLLBAR 

Scrollbar 

Scroll  Bars 

COLOR-BACKGROUND 

Background 

Desktop 

COLOR-ACTIVECAPTION 

ActiveTitle 

Active  Title  Bar 

COLOR-INACTIVECAPTION 

InactiveTitle 

Inactive  Title  Bar 

COLOR-MENU 

Menu 

Menu  Bar 

COLOR-WINDOW 

Window 

Window  Background 

COLOR-WINDOWFRAME 

WindowFrame 

Window  Frame 

COLOR-MENUTEXT 

MenuText 

Menu  Text 

COLOR-WINDOWTEXT 

WindowText 

Window  Text 

(continued) 
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GetSysColor  &  SetSysColor 

WIN.  IN I 

Control  Panel 

COLOR-CAPTIONTEXT 

TitleText 

Active  Title  Bar  Text 

COLOR-INACTIVECAPTIONTEXT 

InactiveTitleText 

Inactive  Title  Bar  Text 

COLOR-ACTIVEBORDER 

ActiveBorder 

Active  Border 

COLOR-INACTIVEBORDER 

InactiveBorder 

Inactive  Border 

COLOR-APPWORKSPACE 

AppWorkspace 

Application  Workspace 

COLOR-HIGHLIGHT 

Highlight 

Highlight 

COLOR-HIGHLIGHTTEXT 

HighlightText 

Highlighted  Text 

COLOR  _BTN  FACE 

ButtonFace 

Button  Face 

COLOR-BTNSHADOW 

ButtonShadow 

Button  Shadow 

COLOR-GRAYTEXT 

GrayText 

Disabled  Text 

COLOR-BTNTEXT 

ButtonText 

Button  Text 

COLOR-BTNHIGHLIGHT 

ButtonHighlight 

Button  Highlight 

Most  of  these  are  self-explanatory.  COLOR -BACKGROUND  is  the  color  of  the  desk¬ 
top  area  behind  all  the  windows.  The  COLOR-WINDOWFRAME  color  is  the  color  used  for 
lines  drawn  between  many  of  the  sections  of  the  display,  such  as  between  a  menu  and  a 
client  area.  The  two  “Highlight”  colors  involve  selected  options  in  menus  and  list  boxes. 
Five  system  colors  determine  the  colors  used  in  push  buttons. 

Default  values  for  these  21  colors  are  provided  by  the  display  driver.  Windows  uses 
these  default  values  unless  they  are  overriden  by  the  [colors]  section  ofWIN.INI. 

The  Button  Colors 

COLOR-WINDOW  and  COLOR-WINDOWTEXT  are  used  by  many  windows  to  color 
themselves.  The  button  controls  (with  the  exception  of  push  buttons)  use  COLOR -WIN¬ 
DOW  to  color  the  background  behind  the  button.  (For  a  group  box,  COLOR -WINDOW  is 
used  only  for  the  background  behind  the  text.)  The  button  controls  use  COLOR-WIN¬ 
DOWTEXT  for  text,  for  the  box  in  a  check  box  control,  and  for  the  round  button  in  a 
radio-button  control.  The  outline  of  push  buttons  and  group  boxes  is  defined  by  using 
COLOR-WINDOWFRAME. 

You  can  use  one  of  two  methods  to  make  your  main  window  and  the  child  window 
control  consistent  in  their  use  of  colors.  The  first  method  is  to  use  system  colors  for  your 
main  window.  To  begin,  you  use  COLOR-WINDOW  for  the  background  of  your  client  area 
when  defining  the  window  class: 

wndclass.hbrBackground  =  C0L0R_WI NDOW  +  1  ; 

(Windows  requires  that  you  add  1  when  you  use  these  identifiers  in  your  wndclass  struc¬ 
ture,  but  doing  so  has  no  profound  purpose  other  than  to  prevent  the  value  from  being  0.) 
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But  that  causes  another  problem.  When  you  display  text  using  TextOut ,  Windows  uses 
values  defined  in  the  device  context  for  the  text  background  color  (which  erases  the  back¬ 
ground  behind  the  text)  and  the  text  color.  The  default  values  are  white  (background)  and 
black  (text)  regardless  of  both  the  system  colors  and  the  hbrBackground  field  of  the  win¬ 
dow  class  structure.  So  you  need  to  use  SetTextColor  and  SetBkColor  to  change  your  text 
and  text  background  colors  to  the  system  colors.  You  do  this  after  you  obtain  the  handle  to 
a  device  context: 

SetBkColor  (hdc.  GetSysColor  ( CO L0R_W I NDOW ) )  ; 

SetTextColor  (hdc,  GetSysColor  ( CO L0R_W I NDOWTEXT ) )  ; 

Now  the  client-area  background,  text  background,  and  text  color  are  all  consistent  with 
the  button  colors.  That’s  the  first  method. 

The  second  method  is  to  force  the  child  window  controls  to  use  the  colors  you  want  to 
use.  This  method  is  a  little  more  involved;  it  requires  processing  WM_CTLCOLOR  messages. 

The  WM  _CTLCOLOR  Messages 

WM_CTLCOLOR  is  a  message  that  a  predefined  child  window  control  sends  to  its  parent 
window  procedure  when  the  child  window  is  about  to  paint  its  client  area.  The  parent 
window  can  use  this  opportunity  to  alter  the  colors  that  the  child  window  procedure  will 
use  for  painting. 

When  the  parent  window  procedure  receives  a  WM_CTLCOLOR  message,  the 
wParam  and  IParam  parameters  have  the  following  meanings: 

ivParam  Handle  to  child  window’s  device  context 

LOWORD  ( IParam )  Handle  to  child  window 

HIWORD  ( IParam )  Type  of  window 


The  high  word  of  IParam  can  be  one  of  the  following: 


HIWORD  (IParam) 

Type  of  Window 

CTLCOLOR-MSGBOX 

Message  box 

CTLCOLOR-EDIT 

Edit  control 

CT  LCOLOR  -LISTBOX 

List  box  control 

CTLCOLOR-BTN 

Button  control 

CTLCOLOR-DLG 

Dialog  box 

CTLCOLOR-SCROLLBAR 

Scroll  bar  control 

CT  LCOLOR -STATIC 

Static  control 

Right  now,  we’re  interested  in  CTLCOLOR-BTN,  the  WM_CTLCOLOR  message  from  a  but¬ 
ton  control.  When  the  parent  window  procedure  gets  this  message,  the  child  window  con¬ 
trol  has  already  obtained  its  device  context.  The  handle  to  this  device  context  is  in 
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wParam.  Any  GDI  (Graphics  Device  Interface)  calls  you  make  using  this  device  context 
will  affect  the  painting  that  the  child  window  does  when  you  pass  control  back  to  the 
child  window. 

You  must  perform  three  actions  when  processing  a  WM-CTLCOLOR  message: 

■  Set  a  text  color  using  SetTextColor. 

■  Set  a  background  color  using  SetBkColor. 

■  Return  a  handle  to  a  brush  to  the  child  window. 

A  “brush”  is  a  GDI  object  that  defines  a  bitmapped  pattern  of  pixels.  Windows  uses 
brushes  to  fill  areas  with  color.  You  can  get  a  handle  to  a  brush  using  GetStockOb- 
ject,  CreateSolidBrush ,  Crea teHa tch Brush ,  or  CreatePatternBrush.  For  processing  the 
WM_CTLCOLOR  message,  you’ll  probably  use  CreateSolidBrush.  Before  your  program  ter¬ 
minates,  you  must  explicitly  delete  any  brushes  you  create.  A  good  time  to  do  this  is  while 
processing  the  WM_DESTROY  message. 

For  most  child  window  controls,  the  color  you  set  in  SetBkColor  should  be  the  same  as 
the  color  of  the  brush  you  return  from  the  WM_CTLCOLOR  message.  For  instance,  button 
controls  use  the  brush  to  color  the  background  of  the  entire  child  window  client  area.  The 
text  background  color  is  used  only  for  the  background  behind  the  text.  These  two  colors 
should  be  the  same.  To  see  how  this  works,  let’s  take  an  example  of  processing  a  WM- 
-CTLCOLOR  message  for  button  controls  where  the  window  procedure  simply  sets  the 
normal  default  colors.  During  initialization  (probably  when  processing  a  WM_CREATE 
message),  you  can  create  a  brush: 

hBrush  =  CreateSolidBrush  (GetSysColor  ( C0L0R_WI NDOW ) )  ; 

The  hBrush  brush  handle  should  be  stored  in  a  static  variable.  Here’s  what  the  WM- 
_CTLCOLOR  processing  looks  like: 

case  WM_CTLC0 LOR  : 

if  (HIWORD  (1 Param)  ==  CTLC0L0R_BTN) 

{ 

SetBkColor  (wParam,  GetSysColor  ( C0L0R_WI NDOW ) )  ; 

SetTextColor  (wParam,  GetSysColor  ( C0L0R_W I NDOWTEXT ) )  ; 

Unreal izeObject  (hBrush)  ; 
point. x  =  point. y  =  0  ; 

Cl ientToScreen  (hwnd,  & p o i n t )  ; 

SetBrushOrg  (wParam,  point. x,  point. y)  ; 

return  ((DWORD)  hBrush)  ; 

} 

break  ; 

Note  that  wParam  is  the  device  context  handle  of  the  button  control.  The  four  statements 
that  culminate  in  the  SetBrushOrg  call  require  some  further  explanation. 
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As  noted  earlier,  a  brush  defines  a  bitmapped  pattern  of  pixels.  When  Windows  uses 
this  brush  to  fill  an  area  with  color,  the  pattern  of  the  brush  is  repeated  horizontally  and 
vertically  until  the  area  is  filled.  The  origin  of  this  brush — the  place  where  Windows 
assumes  the  repeating  pattern  begins — is  the  upper  left  corner  of  the  client  area  associ¬ 
ated  with  the  device  context. 

But  if  you  color  both  the  client  area  of  a  parent  window  and  the  client  area  of  a  child 
window  with  this  same  brush,  the  pattern  won’t  merge  correctly  at  the  edge  of  the  child 
window  because  Windows  is  using  two  different  origins  for  the  same  brush.  To  avoid  this 
problem,  you  call  UnrealizeObject.  This  function  causes  Windows  to  reset  the  origin  of  the 
brush  the  next  time  it  is  selected  into  a  device  context  (which  will  follow  the  return  from 
the  WM-CTLCOLOR  processing).  The  origin  Windows  will  use  is  the  one  you  set  with 
SetBrushOrg-,  in  this  example,  the  function  sets  the  brush  origin  to  the  screen  origin  of  the 
parent  window.  (Don’t  use  UnrealizeObject  for  a  stock  brush  handle  that  you  obtain  from 
GetStockObject ,  and  don’t  worry  if  this  sounds  a  bit  obscure  right  now.  We’ll  cover  the 
issues  in  more  depth  in  Chapter  12.) 

The  brush  in  our  example  is  based  on  the  system  color  COLOR-WINDOW.  If  this 
color  changes  while  the  program  is  running,  the  window  procedure  receives  a 
WM_SYSCOLORCHANGE  message.  The  program  deletes  the  brush  and  creates  a  new  one: 

case  WM_SYSCOLORCHANGE  : 

DeleteObject  (hBrush)  ; 

hBrush  =  CreateSol idBrush  (GetSysColor  ( C0L0R_WI NDOW ) )  ; 
return  0  ; 

Finally,  when  the  program  is  about  to  terminate,  the  brush  should  be  deleted: 

case  WM_DESTROY  : 

DeleteObject  (hBrush)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

I’ve  shown  here  how  you  can  reproduce  the  default  processing  of  WM_CTLCOLOR 
messages  for  button  controls.  Using  your  own  colors  is  much  the  same.  You  would  not  need 
to  trap  WM-SYSCOLORCHANGE  messages  unless  you  wanted  to  base  the  brush  on  a  sys¬ 
tem  color.  We’ll  come  back  to  WM_CTLCOLOR  messages  later  in  this  chapter,  when  we  use 
the  COLORS1  program. 

Owner-Draw  Buttons 

If  you  wish  to  have  total  control  over  the  visual  appearance  of  a  button  but  don’t  want  to 
bother  with  keyboard  logic,  you  can  create  a  button  with  the  BS-OWNERDRAW  style.  This 
is  demonstrated  in  the  OWNDERDRW  program  shown  in  Figure  6-3  on  the  following  page. 
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OWNERDRW.MAK 

# . 

#  OWNERDRW.MAK  make  file 

#  . 

ownerdrw.exe  :  ownerdrw.obj  ownerdrw.def 

$(WINLINK)  ownerdrw,  ownerdrw,  NUL,  $ (WINLIB) ,  ownerdrw 
re  -t  ownerdrw.exe 

ownerdrw.obj  :  ownerdrw. c 
$(WINCC)  ownerdrw. c 


OWNERDRW.C 

/* . - . 

OWNERDRW.C  --  Owner-Draw  Button  Demo  Program 
(c)  Charles  Petzold,  1992 
. */ 


♦include  <windows.h> 

♦define  IDC_SMALLER  1 

♦define  IDC.LARGER  2 


♦define  BTN_WI DTH  (8  *  cxChar) 

♦define  BTN_H EIGHT  (4  *  cyChar) 

long  FAR  PASCAL  ..export  WndProc  (HWND,  UINT,  UINT.  LONG)  ; 


HANDLE  hlnst  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "OwnerDrw"  ; 

MSG  msg  ; 

HWND  hwnd  ; 

WNDCLASS  wndclass  ; 

hlnst  =  hlnstance  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  !  CS_VREDRAW  ; 

wndclass. IpfnWndProc  =  WndProc  ; 


Figure  6-3.  The  OWNERDRW  program. 


(continued) 


Chapter  6:  Child  Window  Controls 


wndclass.cbClsExtra 

wndclass.cbWndExtra 

wndclass.hlnstance 

wndclass.hlcon 

wndclass.hCursor 

wndclass.hbrBackground 

wndclass.lpszMenuName 

wndclass.lpszClassName 


0  ; 

hlnstance  ; 

Loadlcon  (NULL,  I DI_APPLI CATI ON ) 
LoadCursor  (NULL,  IDC.ARROW)  ; 
GetStockObject  (WHIT E_B RUSH)  ; 
szAppName  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "Owner-Draw  Button  Demo", 
WS_OVERLAPP EDWIN DOW, 

CW_USEDEFAULT,  CW.USEDEFAULT, 
CWJJSEDEFAULT,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  Triangle  (HDC  hdc,  POINT  pt [ ] ) 

{ 

SelectObject  (hdc,  GetStockObject  (BLACK_BRUSH) )  ; 

Polygon  (hdc,  pt,  3)  ; 

SelectObject  (hdc,  GetStockObject  (WHITE_BRUSH) )  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HWND  hwndSmaller,  hwndLarger  ; 

static  short  cxClient,  cyClient,  cxChar,  cyChar  ; 

LPDRAWITEMSTRUCT  lpdis  ; 

POINT  pt  [3]  ; 

RECT  re  ; 

short  cx,  cy  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

cxChar  =  LOWORD  (GetDial ogBaseUnits  0)  ; 
cyChar  =  HIWORD  (GetDialogBaseUnits  0)  ; 


(continued) 
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//  Create  the  owner-draw  push  buttons 

hwndSmaller  =  CreateWindow  ("button",  "", 

WS.CHILD  !  WS__V I S I B LE  !  BS_OWNERDRAW, 

0,  0,  BTN.WIDTH,  BTN_HEIGHT, 
hwnd,  IDC_SMALLER,  hlnst,  NULL)  ; 

hwndLarger  =  CreateWindow  ("button",  "", 

WS_CHI LD  !  WS_V I S I B LE  !  BS.OWNERDRAW, 

0,  0,  BTN.WIDTH,  BTN.HEIGHT, 
hwnd,  IDC.LARGER,  hlnst,  NULL)  ; 

return  0  ; 
case  WM_SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HIWORD  (IParam)  ; 

//  Move  the  buttons  to  the  new  center 

MoveWindow  (hwndSmaller,  cxClient  /  2  -  3  *  BTN_WIDTH  /  2, 

cyClient  /  2  -  BTN_HE I GHT  /  2, 

BTN_W I DTH ,  BTN_HEIGHT,  TRUE)  ; 

MoveWindow  (hwndLarger,  cxClient  /  2  +  BTN_WI DTH  /  2, 

cyClient  /  2  -  BTN_HEI GHT  /  2, 

BTN_WI DTH ,  BTN_H E I GHT ,  TRUE)  ; 

return  0  ; 

case  WM.COMMAND  : 

GetWindowRect  (hwnd,  &rc)  ; 

//  Make  the  window  10%  smaller  or  larger 

switch  (wParam) 

{ 

case  IDC_SMALLER  : 

rc.left  +=  cxClient  /  20  ; 

rc. right  -=  cxClient  /  20  ; 

rc.top  +=  cyClient  /  20  ; 

rc. bottom  -=  cyClient  /  20  ; 

break  ; 

case  IDC.LARGER  : 

rc.left  -=  cxClient  /  20  ; 

rc. right  +=  cxClient  /  20  ; 

rc.top  -=  cyClient  /  20  ; 

rc. bottom  +=  cyClient  /  20  ; 

break  ; 
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MoveWindow  (hwnd,  rc.left,  rc.top,  rc. right  -  rc.left, 

rc. bottom  -  rc.top.  TRUE)  ; 


return  0  ; 


case  WM.DRAWITEM  : 

lpdis  =  (LPDRAWITEMSTRUCT)  lParam  ; 

//  Fill  area  with  white  and  frame  it  black 

Fill Rect  (lpdis->hDC,  &1 pdis->rcltem, 

GetStockObject  (WHITE_BRUSH) )  ; 

FrameRect  (lpdis->hDC.  &lpdis->rcltem, 

GetStockObject  (BLACK_BRUSH) )  ; 

//  Draw  inward  and  outward  black  triangles 

cx  =  lpdis ->rcltem. right  -  1 pdi s ->rcl tem. left  ; 
cy  =  lpdis->rcltem. bottom  -  lpdis->rcItem.top  ; 

switch  (lpdis- >Ctl ID) 

{ 

case  IDC_SMALLER  : 

pt[0].x  =  3  *  cx  /  8  ;  pt[0].y  =  1  *  cy  /  8 

pt[l].x  =  5  *  cx  /  8  ;  pt[l].y  =  1  *  cy  /  8 

pt[2].x  =  4  *  cx  /  8  ;  pt[2].y  =  3  *  cy  /  8 

Triangle  (lpdis - >hDC ,  pt)  ; 

pt [0] . x  =  7  *  cx  /  8  ;  pt[0].y  =  3  *  cy  /  8 

pt[l].x  =  7  *  cx  /  8  ;  pt[l].y  =  5  *  cy  /  8 

pt [2] . x  =  5  *  cx  /  8  ;  pt[2].y  =  4  *  cy  /  8 

Triangle  (lpdis->hDC,  pt)  ; 

pt [0] . x  =  5  *  cx  /  8  ;  pt[0].y  =  7  *  cy  /  8 

pt[l].x  =  3  *  cx  /  8  ;  pt[l].y  =  7  *  cy  /  8 

pt[2].x  =  4  *  cx  /  8  ;  pt[2].y  =  5  *  cy  /  8 

Triangle  (lpdis->hDC.  pt)  ; 

pt[0].x  =  1  *  cx  /  8  ;  pt[0].y  =  5  *  cy  /  8 

pt[l].x  =  1  *  cx  /  8  ;  pt[l].y  =  3  *  cy  /  8 

pt[2].x  =  3  *  cx  /  8  ;  pt[2].y  =  4  *  cy  /  8 

Triangle  (lpdis->hDC,  pt)  ; 

break  ; 

case  IDC_LARGER  : 


(continued) 
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pt [0] . x  =  5  *  cx  /  8  ;  pt[0].y  =  3  *  cy  /  8 

pt[l].x  =  3  *  cx  /  8  ;  pt[l].y  =  3  *  cy  /  8 

pt[2].x  =  4  *  cx  /  8  ;  pt[2].y  =  1  *  cy  /  8 

Triangle  (lpdis->hDC,  pt)  ; 

pt [0] . x  =  5  *  cx  /  8  ;  pt[0].y  =  5  *  cy  /  8 

pt[l].x  =  5  *  cx  /  8  ;  pt[l].y  =  3  *  cy  /  8 

pt[2].x  =  7  *  cx  /  8  ;  pt[2].y  =  4  *  cy  /  8 

Triangle  (lpdis->hDC,  pt)  ; 

pt [0] . x  =  3  *  cx  /  8  ;  pt[0].y  =  5  *  cy  /  8 

pt[l].x  =  5  *  cx  /  8  ;  pt[l].y  =  5  *  cy  /  8 

pt[2].x  =  4  *  cx  /  8  ;  pt[2].y  =  7  *  cy  /  8 

Triangle  (lpdis->hDC,  pt)  ; 

pt [0] . x  =  3  *  cx  /  8  ;  pt[0].y  =  3  *  cy  /  8 

pt [1 ] . x  =  3  *  cx  /  8  ;  pt[l].y  =  5  *  cy  /  8 

pt[2].x  =  1  *  cx  /  8  ;  pt[2].y  =  4  *  cy  /  8 

Triangle  (lpdis->hDC,  pt)  ; 

break  ; 

} 


//  Invert  the  rectangle  if  the  button  is  selected 

if  ( 1 pdi s ->i temState  &  ODS_SELECTED) 

InvertRect  (lpdis->hDC,  &1 pdis->rcltem)  ; 


//  Draw  a  focus  rectangle  if  the  button  has  the  focus 


if  ( 1 pdi s ->i temState  &  0DS_F0CUS) 

{ 

1 pdi s ->rcl tem. 1  eft  +=  cx  /  16 

lpdis->rcItem.top  +=  cy  /  16 

lpdis->rcltem. right  -=  cx  /  16 

lpdis->rcltem. bottom  -=  cy  /  16 


DrawFocusRect  ( 1 pdi s ->hDC ,  &lpdis->rcltem)  ; 

} 


return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 
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OWNERDRW.DEF 


OWNERDRW. DEF  module  definition  file 


NAME  OWNERDRW 

DESCRIPTION  'Owner-Draw  Button  Demo  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 

This  program  contains  two  buttons  in  the  center  of  its  client  area,  as  shown  in  Figure 
6-4.  The  button  on  the  left  has  four  triangles  pointing  to  the  center  of  the  button.  Clicking 
the  button  decreases  the  size  of  the  window  by  10%.  The  button  on  the  right  has  four 
triangles  pointing  outward,  and  clicking  this  button  increases  the  window  size  by  10%. 


Figure  6-4.  The  OWNERDRW  display. 

Most  programs  that  use  the  BS_OWNERDRAW  button  style  to  draw  their  own  buttons 
often  use  small  bitmaps  for  the  button  images.  However,  because  we  won’t  be  learning 
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how  to  use  pre-drawn  bitmaps  until  Chapter  8,  the  OWNERDRW  program  simply  draws 
the  rectangles  on  the  surface  of  the  buttons. 

During  the  WM -CREATE  message,  OWNERDRW  obtains  the  average  width  and 
height  of  the  system  font  by  calling  the  GetDialogBaseUnits  function.  This  is  a  function 
new  in  Windows  3.0  that  is  often  very  handy  for  obtaining  this  information.  OWNERDRW 
then  creates  two  buttons  with  the  BS -OWNERDRW  style;  the  buttons  are  given  a  width  of 
eight  times  the  system  font  and  four  times  the  system  font  height.  (When  using  predefined 
bitmaps  to  draw  buttons,  it’s  useful  to  know  that  these  dimensions  create  buttons  that  are 
64  pixels  by  64  pixels  on  a  VGA.)  The  buttons  are  not  yet  positioned.  During  the  WM-SIZE 
message,  OWNERDRW  positions  the  buttons  in  the  center  of  the  client  area  by  calling 
MoveWindow. 

Clicking  on  the  buttons  causes  them  to  generate  WM -COMMAND  messages,  when 
wParam  is  equal  to  the  control  window  ID  that  was  passed  as  a  parameter  to  the 
CreateWindow  function  that  originally  created  them.  To  process  the  WM-COMMAND 
message,  OWNERDRW  calls  GetWindowRect  to  store  the  position  and  size  of  the  entire 
window  (not  only  the  client  area)  in  a  RECT  (rectangle)  structure.  This  position  is  relative 
to  the  screen.  OWNERDRW  then  adjusts  the  fields  of  this  rectangle  structure  depending  on 
whether  the  left  or  right  button  was  clicked.  Then  the  program  repositions  and  resizes  the 
window  by  calling  MoveWindow .  This  generates  another  WM-SIZE  message,  and  the  but¬ 
tons  are  repositioned  in  the  center  of  the  client  area. 

If  this  were  all  the  program  did,  it  would  be  entirely  functional  but  the  buttons  would 
not  be  visible.  A  button  created  with  the  BS-OWNERDRAW  style  sends  its  parent  window 
a  WM-DRAWITEM  message  whenever  the  button  needs  to  be  repainted.  This  occurs 
when  the  button  is  first  created,  when  it  is  pressed  or  released,  when  it  gains  or  loses  the 
input  focus,  and  whenever  else  it  needs  repainting. 

During  the  WM_DRAWITEM  message,  the  iParam  message  parameter  is  a  far  pointer 
to  a  structure  of  type  DRAWITEMSTRUCT.  The  OWNERDRW  program  stores  this  far 
pointer  in  a  variable  named  Ipdis.  This  structure  contains  the  information  necessary  for  a 
program  to  draw  the  button.  (The  same  structure  is  also  used  for  owner-draw  list  boxes 
and  menu  items.)  The  structure  fields  important  for  working  with  buttons  are  hDC{ the  de¬ 
vice  context  for  the  button),  rcltem  (a  RECT  structure  providing  the  size  of  the  button), 
CtllD  (the  control  window  ID),  and  itemState  (which  indicates  whether  the  button  is 
pushed  or  has  the  input  focus). 

OWNERDRW  begins  WM_DRAWITEM  processing  by  calling  FillRect  to  erase  the 
surface  of  the  button  with  a  white  brush,  and  FrameRectl o  draw  a  black  frame  around  the 
button.  Then,  OWNERDRW  draws  four  black-filled  triangles  on  the  button  by  calling 
Polygon.  That’s  the  normal  case. 

If  the  button  is  currently  being  pressed,  then  a  bit  of  the  itemState  field  of  the 
DRAWITEMSTRUCT  will  be  set.  You  can  test  this  bit  using  the  ODS-SELECTED  constant. 
If  the  bit  is  set,  OWNERDRW  inverts  the  colors  of  the  button  by  calling  InvertRect. 
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If  the  button  has  the  input  focus,  then  the  ODS-FOCUS  bit  of  the  itemState  field  will  be  set. 
In  this  case,  OWNERDRW  draws  a  dotted  rectangle  just  inside  the  periphery  of  the  button 
by  calling  DrawFocusRect. 

A  word  of  warning  when  using  owner-draw  buttons:  Windows  obtains  a  device  con¬ 
text  for  you  and  includes  it  as  a  field  of  the  DRAWITEMSTRUCT  structure.  Leave  the  device 
context  in  the  same  state  you  found  it.  Any  GDI  objects  selected  into  the  device  context 
must  be  unselected.  Also,  be  careful  not  to  draw  outside  the  rectangle  defining  the  bound¬ 
aries  of  the  button. 


THE  STATIC  CLASS 


You  create  a  static  child  window  control  by  using  “static”  as  the  window  class  in  the 
CreateWindow function.  These  are  fairly  benign  child  windows.  They  do  not  accept  mouse 
or  keyboard  input,  and  they  do  not  send  WMXOMMAND  messages  back  to  the  parent 
window.  (When  you  move  or  click  the  mouse  over  a  static  child  window,  the  child  window 
traps  the  WM_NCHITTEST  message  and  returns  a  value  of  HTTRANSPARENT  to  Win¬ 
dows.  This  causes  Windows  to  send  the  same  WM_NCHITTEST  message  to  the  underlying 
window,  which  is  usually  the  parent.  The  parent  usually  passes  the  message  to  DefWin- 
dowProc ,  where  it  is  converted  to  a  client-area  mouse  message.) 

The  first  six  static  window  styles  simply  draw  a  rectangle  or  a  frame  in  the  client  area 
of  the  child  window.  The  “RECT”  static  styles  (left  column  below)  are  filled-in  rectangles; 
the  three  “FRAME”  styles  (right  column)  are  rectangular  outlines  that  are  not  filled  in: 


SS-BLACKRECT 

SS-BLACKFRAME 

SS-GRAYRECT 

SS-GRAYFRAME 

SS-WHITERECT 

SS-WHITEFRAME 

“BLACK,”  “GRAY,”  and 

“WHITE”  do  not  mean  the  colors 

Rather,  the  colors  are  based  on  system  colors  as  shown  here: 

Static  Control 

System  Color 

BLACK 

COLOR  -WINDOWFRAME 

GRAY 

COLOR  -BACKGROUND 

WHITE 

COLOR -WINDOW 

Most  display  drivers  define  default  settings  of  black  for  COLOR -WINDOWFRAME 
and  white  for  COLOR -WINDOW.  (Of  course,  a  user  can  change  any  of  these  colors  using 
the  Control  Panel  program  in  Windows.)  The  colors  used  in  the  “RECT”  and  “FRAME” 
static  styles  cannot  be  changed  by  trapping  WM-CTLCOLOR  messages.  The  window  text 
field  of  the  CreateWindow  call  is  ignored  for  these  styles.  The  upper  left  corner  of  the  rect¬ 
angle  begins  at  the  x  position  and  y  position  coordinates  relative  to  the  parent  window. 
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The  static  class  also  includes  three  text  styles:  SS-LEFT,  SS-RIGHT,  and  SS_CEN- 
TER.  These  create  left-justified,  right-justified,  and  centered  text.  The  text  is  given  in  the 
window  text  parameter  of  the  CreateWindow  call,  and  it  can  be  changed  later  using  Set- 
WindowText.  When  the  window  procedure  for  static  controls  displays  this  text,  it  uses  the 
DrawText  function  with  DT_WORDBREAK,  DT_NOCLIP,  and  DT-EXPANDTABS  parame¬ 
ters.  The  text  is  wordwrapped  within  the  rectangle  of  the  child  window.  The  background 
of  these  three  text-style  child  windows  is  normally  COLOR-WINDOW,  and  the  text  itself  is 
COLOR-WINDOWTEXT.  When  you  intercept  WM-CTLCOLOR  messages,  you  can  change 
the  text  color  by  calling  SetTextColor  and  the  background  color  by  calling  SetBkColor and 
by  returning  the  handle  to  the  background  brush. 

Finally,  the  static  class  also  includes  the  window  styles  SS-ICON  and  SS-USERITEM. 
However,  these  have  no  meaning  when  used  as  child  window  controls.  We’ll  look  at  them 
again  when  discussing  dialog  boxes. 

THE  SCROLL  BAR  CLASS 

When  the  subject  of  scroll  bars  first  came  up  in  Chapter  2  while  I  was  designing  the 
SYSMETS  series  of  programs,  I  discussed  some  of  the  differences  between  “window  scroll 
bars”  and  “scroll  bar  controls.”  SYSMETS  uses  window  scroll  bars,  which  appear  at  the 
right  and  bottom  of  the  window.  You  add  window  scroll  bars  to  a  window  by  including  the 
identifier  WS-VSCROLL  or  WS-HSCROLL  or  both  in  the  window  style  when  creating  the 
window.  Now  we’re  ready  to  make  some  scroll  bar  controls,  which  are  child  windows  that 
can  appear  anywhere  in  the  client  area  of  the  parent  window.  You  create  child  window 
scroll  bar  controls  by  using  the  predefined  window  class  “scrollbar”  and  one  of  the  two 
scroll  bar  styles  SBS-VERT  and  SBS-HORZ. 

Unlike  the  button  controls  (and  the  edit  and  list  box  controls  to  be  discussed  later), 
scroll  bar  controls  do  not  send  WM-COMMAND  messages  to  the  parent  window.  Instead, 
they  send  WM-VSCROLL  and  WM-HSCROLL  messages,  just  like  window  scroll  bars.  When 
processing  the  scroll  bar  messages,  you  can  differentiate  between  window  scroll  bars  and 
scroll  bar  controls  by  the  high  word  of  the  IParam  parameter: 


Scroll  Bar  Type 

HI  WORD  (IParam) 

Window  scroll  bar 

Scroll  bar  control 

0 

Window  handle  of  control 

The  wParam  parameter  and  the  low  word  of  IParam  have  the  same  meaning  for  window 
scroll  bars  and  scroll  bar  controls. 

Although  window  scroll  bars  have  a  fixed  width,  Windows  uses  the  full  rectangle 
dimensions  given  in  the  CreateWindow  call  (or  later  in  the  MoveWindow  call)  to  size  scroll 
bar  controls.  You  can  make  long,  thin  scroll  bar  controls  or  short,  pudgy  scroll  bar  controls. 
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If  you  want  to  create  scroll  bar  controls  that  have  the  same  dimensions  as  window  scroll 
bars,  you  can  use  GetSystemMetrics  to  obtain  the  height  of  a  horizontal  scroll  bar: 

GetSystemMetrics  (SM.CYHSCROLL)  ; 

or  the  width  of  a  vertical  scroll  bar: 

GetSystemMetrics  (SM_CXVSCROLL)  ; 

(The  scroll  bar  window  style  identifiers  SBS-LEFTALIGN,  SBS-RIGHTALIGN,  SBS-TOP- 
ALIGN,  and  SBS_BOTTOMALIGN  are  documented  to  give  standard  dimensions  to  scroll 
bars.  However,  these  styles  work  only  for  scroll  bars  in  dialog  boxes.) 

You  can  set  the  range  and  position  of  a  scroll  bar  control  with  the  same  calls  used  for 
window  scroll  bars: 

SetScrol 1  Range  (hwndScroll,  SELCTL,  nMin,  nMax,  bRedraw)  ; 

SetScrollPos  (hwndScroll.  SELCTL,  nPos,  bRedraw)  ; 

The  difference  is  that  window  scroll  bars  use  a  handle  to  the  parent  window  as  the  first 
parameter  and  SB-VERT  or  SB_HORZ  as  the  second  parameter. 

The  interior  bar  of  the  scroll  bar  is  COLOR -SCROLLBAR.  The  thumb  and  arrow 
colors  are  based  on  the  push-button  colors.  If  you  trap  WM-CTLCOLOR  messages,  you  can 
return  a  brush  from  the  message  to  override  this  color.  Let’s  do  it. 

The  COLORS1  Program 

To  see  some  uses  of  scroll  bars  and  static  child  windows — and  also  to  explore  color  in 
more  depth — we’ll  use  the  COLORS1  program,  shown  in  Figure  6-5.  COLORS1  displays 
three  scroll  bars  in  the  left  half  of  the  client  area  labeled  “Red,”  “Green,”  and  “Blue.”  As 
you  scroll  the  scroll  bars,  the  right  half  of  the  client  area  changes  to  the  composite  color  in¬ 
dicated  by  the  mix  of  the  three  primary  colors.  The  numeric  values  of  the  three  primary 
colors  are  displayed  under  the  three  scroll  bars. 

COLORS1  .MAK 

# 

#  C0L0RS1 .MAK  make  file 
#-- . - . 

colorsl.exe  :  colorsl.obj  colorsl.def 

$(WINLINK)  colorsl,  colorsl,  NUL,  $(WINLIB),  colorsl 
rc  -t  colorsl.exe 

colorsl.obj  :  colorsl. c 
$ ( W I NCC )  colorsl. c 

Figure  6-5.  The  COLORS1  program. 
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COLORS'!  .C 


/* . - . - - - 

C0L0RS1.C  --  Colors  Using  Scroll  Bars 
(c)  Charles  Petzold,  1992 

*/ 


//include  <windows.h> 

//include  <stdlib.h> 

//define  min(a,b)  (((a)  <  (b) )  ?  (a)  :  (b) ) 

//define  max(a,b)  (((a)  >  (b))  ?  (a)  :  (b) ) 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

long  FAR  PASCAL  .export  ScrollProc  (HWND,  UINT,  UINT,  LONG)  ; 

FARPROC  1 pf nOl dScr [3]  ; 

HWND  hwndScrol [3] ,  hwndLabel [3] ,  hwndVal ue[3] ,  hwndRect  ; 
short  color[3],  nFocus  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Colorsl"  ; 

static  char  *szCol orLabel []  =  {  "Red",  "Green",  "Blue"  }  ; 

FARPROC  IpfnScrol 1 Proc  ; 

HWND  hwnd  ; 

MSG  msg  ; 

short  n  ; 

WNDCLASS  wndclass  ; 


if  (hPrevInstance) 
return  FALSE  ; 


wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbrBackg round 
wndclass. IpszMenuName 
wndclass. lpszClassName 


CS.HREDRAW  !  CS.VREDRAW  ; 
WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

NULL  ; 

LoadCursor  (NULL,  IDC.ARROW)  ; 
CreateSol idBrush  (0L)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  Uwndclass)  ; 

hwnd  =  CreateWindow  (szAppName,  "Color  Scroll", 

WS.OVERLAPP EDWIN DOW  !  WS.C L I PCH I LDREN , 
CW.USEDEFAULT,  CW.USEDE FAU LT , 


(continued) 
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CWJJSEDEFAULT,  CWJJSEDE FAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

hwndRect  =  CreateWindow  ("static”,  NULL, 

WS_CHILD  !  WS_V I S I BLE  !  SS_WH I TERECT . 

0 ,  0 ,  0 ,  0 , 

hwnd,  9,  hlnstance,  NULL)  ; 

IpfnScrollProc  =  MakeProcInstance  ( ( FARPROC )  ScrollProc,  hlnstance)  ; 

for  (n  =  0  ;  n  <  3  ;  n++) 

{ 

hwndScrol[n]  =  CreateWindow  ("scrollbar",  NULL, 

WS.CHILD  !  WS_V I S I B LE  !  WS.TABSTOP  !  SBS.VERT, 

0,  0,  0,  0, 

hwnd,  n,  hlnstance,  NULL)  ; 

hwndLabelfn]  =  CreateWindow  ("static",  szColorLabel [n] , 

WS.CHILD  !  WS_V I SI BLE  !  SS.CENTER, 

0 ,  0 ,  0 ,  0 , 

hwnd,  n  +  3,  hlnstance,  NULL)  ; 

hwndValue[n]  =  CreateWindow  ("static",  "0", 

WS.CHILD  !  WS_V I S I B LE  !  SS_CENTER, 

0 ,  0 ,  0 ,  0 , 

hwnd,  n  +  6,  hlnstance,  NULL)  ; 

1 pf nOl dScr [n]  =  (FARPROC)  GetWindowLong  (hwndScrol [n] ,  GWL.WNDPROC)  ; 
SetWindowLong  (hwndScrol [n] ,  GWL_WNDPROC,  (LONG)  IpfnScrollProc)  ; 

SetScroll Range  (hwndScrol [n] ,  SB_CTL,  0,  255,  FALSE)  ; 

SetScrollPos  (hwndScrol [n] ,  SB_CTL,  0,  FALSE)  ; 

} 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HBRUSH  hBrush [3]  ; 
char  szbuffer[10]  ; 

HDC  hdc  ; 


(continued) 


237 


SECTION  II:  READING  INPUT 


POINT  point  ; 

short  n,  cxClient,  cyClient,  cyChar  ; 

TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM_CREATE  : 

hBrush [0]  =  CreateSol idBrush  (RGB  (255,  0,  0))  ; 

hBrush[l]  =  CreateSol idBrush  (RGB  (0,  255,  0))  ; 

hBrush[2]  =  CreateSol idBrush  (RGB  (0,  0,  255))  ; 

return  0  ; 

case  WM.SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HIWORD  (IParam)  ; 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 
cyChar  =  tm.tmHeight  ; 

ReleaseDC  (hwnd,  hdc)  ; 

MoveWindow  (hwnaRect,  0,  0,  cxClient  /  2,  cyClient,  TRUE)  ; 

for  (n  =  0  ;  n  <  3  ;  n++) 

{ 

MoveWindow  (hwndScrol [n] , 

(2  *  n  +  1)  *  cxClient  /  14,  2  *  cyChar, 
cxClient  /  14,  cyClient  -  4  *  cyChar,  TRUE)  ; 

MoveWindow  (hwndLabel [n] , 

(4  *  n  +  1)  *  cxClient  /  28,  cyChar  /  2, 
cxClient  /  7,  cyChar,  TRUE)  ; 

MoveWindow  (hwndVal ue[n] , 

(4  *  n  +  1)  *  cxClient  /  28,  cyClient  -  3  *  cyChar  /  2, 
cxClient  /  7,  cyChar,  TRUE)  ; 

} 

SetFocus  (hwnd)  ; 
return  0  ; 

case  WM.SETFOCUS  : 

SetFocus  (hwndScrol [nFocus])  ; 
return  0  ; 

case  WM_VSCROLL  : 

n  =  GetWindowWord  (HIWORD  (IParam),  GWW.ID)  ; 

switch  (wParam) 

{ 

case  SB.PAGEDOWN  : 
color[n]  +=  15  ; 


(continued) 
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//  fall  through 

case  SB_L I NEDOWN  : 

color[n]  =  min  (255,  color[n]  +  1)  ; 
break  ; 

case  SB_PAGEUP  : 

color[n]  -=  15  ; 

//  fall  through 

case  SB_L I N EU P  : 

color[n]  =  max  (0.  col  or [n]  -  1)  ; 
break  ; 

case  S B_T 0 P  : 

color[n]  =  0  ; 
break  ; 


case  SB.BOTTOM  : 

color[n]  =  255  ; 
break  ; 


case  S B_T HUMBPOSITION  : 
case  SB_THUMBTRACK  : 

color[n]  =  LOWORD  (IParam)  ; 
break  ; 


default  : 
break  ; 

} 

SetScrollPos  (hwndScrol [n] ,  SB_CTL,  color[n],  TRUE)  ; 
SetWindowText  (hwndVal ue[n] ,  itoa  (color[n],  szbuffer,  10))  ; 


DeleteObject  ( SetCl assWord  (hwnd,  GCW_HBRBACKGROUND, 

CreateSol idBrush  (RGB  (color[0],  col  or [1] ,  color[2]))))  ; 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 


case  WM.CTLCOLOR  : 

if  (HIWORD  (IParam)  ==  CTLC0L0R_SCR0LLBAR) 

{ 

Set BkCol or  (wParam,  GetSysColor  ( CO LOR_CAPTIONTEXT ) )  ; 
SetTextCol or  (wParam,  GetSysColor  ( C0L0R_WI NDOWFRAME ) )  ; 

n  =  GetWindowWord  (LOWORD  (IParam),  GWW_ID)  ; 
point. x  =  point. y  =  0  ; 

ClientToScreen  (hwnd,  &point)  ; 

UnrealizeObject  ( hBrush [n] )  ; 

SetBrushOrg  (wParam,  point. x,  point. y)  ; 
return  ((DWORD)  hBrush[n])  ; 

} 

break  ; 


(continued) 
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case  WM_DESTROY  : 

DeleteObject  (SetCl assWord  (hwnd,  GCW.HBRBACKGROUND, 
GetStockObject  (WHITE.BRUSH) ) )  ; 
for  (n  =  0  ;  n  <  3  ;  DeleteObject  (hBrush  [n++]))  ; 
PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

long  FAR  PASCAL  .export  ScrollProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

short  n  =  GetWindowWord  (hwnd,  GWW.ID)  ; 

switch  (message) 

{ 

case  WM.KEYDOWN  : 

if  (wParam  ==  VK.TAB) 

SetFocus  (hwndScrol [(n  + 

(GetKeyState  (VK_SHIFT)  <  0  ?  2  :  D)  %  3])  ; 

break  ; 

case  WM.SETFOCUS  : 
nFocus  =  n  ; 
break  ; 

} 

return  Cal lWindowProc  (1 pf nOl dScr [n] ,  hwnd,  message,  wParam,  IParam)  ; 
} 


COLORS1.DEF 


C0L0RS1.DEF  module  definition  file 


NAME 


C0L0RS1 


DESCRIPTION  'Colors  Using  Scroll  Bars  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


COLORS1  puts  its  children  to  work.  The  program  uses  10  child  window  controls:  3 
scroll  bars,  6  windows  of  static  text,  and  1  static  rectangle.  COLORS1  traps  WM_CTLCOLOR 
messages  to  color  the  interior  sections  of  the  three  scroll  bars  red,  green,  and  blue.  You  can 
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scroll  the  scroll  bars  using  either  the  mouse  or  the  keyboard.  You  can  use  COLORS1  as  a  de¬ 
velopment  tool  in  experimenting  with  color  and  choosing  attractive  (or,  if  you  prefer,  ugly) 
colors  for  your  own  Windows  programs.  A  monochrome  version  of  the  COLORS1  display  is 
shown  in  Figure  6-6;  obviously,  to  take  advantage  of  the  program’s  manipulation  of  color, 
you’ll  need  to  use  a  color  monitor. 


Program  Fie  Manager 
Manager 


Figure  6-6.  A  monochrome  version  of  the  COLORS1  display. 

COLORS1  doesn’t  process  WM_PAINT  messages,  and  the  program  obtains  a  device 
context  handle  only  for  determining  the  height  of  a  character.  Most  of  the  work  in 
COLORS1  is  done  by  the  child  windows. 

The  color  shown  on  the  right  half  of  the  client  area  is  actually  the  window’s  back¬ 
ground  color.  A  static  child  window  with  style  SS-WHITERECT  blocks  out  the  left  half  of 
the  client  area.  The  three  scroll  bars  are  child  window  controls  with  the  style  SBS-VERT. 
These  scroll  bars  are  positioned  on  top  of  the  SS_WHITERECT  child.  Six  more  static  child 
windows  of  style  SS -CENTER  (centered  text)  provide  the  labels  and  the  color  values. 
COLORS1  creates  its  normal  overlapped  window  and  the  ten  child  windows  within  the  Win- 
Main  function  using  CreateWindow.  The  SS_WHITERECT  and  SS -CENTER  static  windows 
use  the  window  class  “static”;  the  three  scroll  bars  use  the  window  class  “scrollbar.” 

The  x  position,  y  position,  width,  and  height  parameters  of  the  CreateWindow  calls 
are  initially  set  to  0  because  the  position  and  sizing  depend  on  the  size  of  the  client  area, 
which  is  not  yet  known.  COLORSl’s  window  procedure  resizes  all  ten  child  windows  using 
MoveWindow  when  it  receives  a  WM-SIZE  message.  So  whenever  you  resize  the  COLORS1 
window,  the  size  of  the  scroll  bars  changes  proportionally. 
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When  the  WndProc  window  procedure  receives  a  WM_VSCROLL  message,  the  high 
word  of  the  iParam  parameter  is  the  handle  to  the  child  window.  We  can  use  GetWindow- 
Word  to  get  the  window  ID  number: 

n  =  GetWindowWord  ( H I  WORD  (IParam),  GWW_I D )  ; 

For  the  three  scroll  bars,  we  have  conveniently  set  the  ID  numbers  to  0,  1,  and  2,  so 
WndProc  can  tell  which  scroll  bar  is  generating  the  message. 

Because  the  handles  to  the  child  windows  were  saved  in  arrays  when  the  windows 
were  created,  WndProc  can  process  the  scroll  bar  message  and  set  the  new  value  of  the 
appropriate  scroll  bar  using  the  SetScrollPos  call: 

SetScrollPos  (hwndScrol [n] ,  SB_CTL,  col  or [n] ,  TRUE)  ; 

WndProc  also  changes  the  text  of  the  child  window  at  the  bottom  of  the  scroll  bar: 

SetWindowText  (hwndVal ue[n] ,  itoa  (col or[n] ,  szbuffer,  10))  ; 

The  Automatic  Keyboard  Interface 

Scroll  bar  controls  can  also  process  keystrokes,  but  only  if  they  have  the  input  focus.  The 
following  table  shows  how  keyboard  cursor  keys  translate  into  scroll  bar  messages: 


Cursor  Key 

Scroll  Bar  Message  wParam  Value 

Home 

SB_TOP 

End 

SB_BOTTOM 

Page  Up 

SB  .PAGEUP 

Page  Down 

SB-PAGEDOWN 

Left  or  Up 

SB-LINEUP 

Right  or  Down 

SB-LINEDOWN 

In  fact,  the  SB_TOP  and  SB -BOTTOM  scroll  bar  messages  can  be  generated  only  by  using 
the  keyboard.  If  you  want  a  scroll  bar  control  to  obtain  the  input  focus  when  the  scroll  bar 
is  clicked  with  the  mouse,  you  must  include  the  WS-TABSTOP  identifier  in  the  window 
class  parameter  of  the  CreateWindow call.  When  a  scroll  bar  has  the  input  focus,  a  blinking 
gray  block  is  displayed  on  the  scroll  bar  thumb. 

To  provide  a  full  keyboard  interface  to  the  scroll  bars,  however,  some  more  work  is 
necessary.  First,  the  WndProc  window  procedure  must  specifically  give  a  scroll  bar  the 
input  focus.  It  does  this  by  processing  the  WM-SETFOCUS  message,  which  the  parent 
window  receives  when  it  obtains  the  input  focus.  WndProc  simply  sets  the  input  focus  to 
one  of  the  scroll  bars: 

SetFocus  (hwndScrol [nFocus])  ; 
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But  you  also  need  some  way  to  get  from  one  scroll  bar  to  another  by  using  the  key¬ 
board,  preferably  by  using  the  Tab  key.  This  is  more  difficult,  because  once  a  scroll  bar  has 
the  input  focus,  it  processes  all  keystrokes.  But  the  scroll  bar  cares  only  about  the  cursor 
keys;  it  ignores  the  Tab  key.  The  way  out  of  this  dilemma  lies  in  a  technique  called 
“window  subclassing.”  We’ll  use  it  to  add  a  facility  to  COLORS1  to  jump  from  one  scroll  bar 
to  another  using  the  Tab  key. 

Window  Subclassing 

The  window  procedure  for  the  scroll  bar  controls  is  somewhere  inside  Windows.  However, 
you  can  obtain  the  address  of  this  window  procedure  by  a  call  to  GetWindowLong  using 
the  GWL-WNDPROC  identifier  as  a  parameter.  Moreover,  you  can  set  a  new  window  pro¬ 
cedure  for  the  scroll  bars  by  calling  SetWindowLong.  This  technique,  called  “window 
subclassing,”  is  very  powerful.  It  lets  you  hook  into  existing  window  procedures,  process 
some  messages  within  your  own  program,  and  pass  all  other  messages  to  the  old  window 
procedure. 

The  window  procedure  that  does  preliminary  scroll  bar  message  processing  in 
COLORS1  is  called  ScrollProc ;  it  is  toward  the  end  of  the  COLORS1.C  listing.  Because 
ScrollProc  is  a  function  within  COLORS1  that  is  called  by  Windows,  it  must  be  defined  as 
FAR  PASCAL  -export. 

First,  to  ensure  that  ScrollProc  accesses  the  proper  data  segment,  COLORS1  must 
obtain  a  far  address  for  the  function  using  MakeProcInstance : 

lpfnScrollProc  =  MakeProcInstance  ( ( FARPROC )  ScrollProc,  hlnstance); 

For  each  of  the  three  scroll  bars,  COLORS1  uses  GetWindowLong  to  obtain  and  save  the 
address  of  the  existing  scroll  bar  window  procedure: 

1 pfnOl dScr[n]  =  (FARPROC)  GetWindowLong  ( hwndScrol [n] ,  GWL.WNDPROC)  ; 

Next,  the  program  sets  the  new  scroll  bar  window  procedure: 

SetWindowLong  (hwndScrol [n] ,  GWL_WNDPROC,  (LONG)  lpfnScrollProc)  ; 

Now  the  function  ScrollProc  gets  all  messages  that  Windows  sends  to  the  scroll  bar 
window  procedure  for  the  three  scroll  bars  in  COLORS1  (but  not,  of  course,  for  scroll  bars 
in  other  programs).  The  ScrollProc  window  procedure  simply  changes  the  input  focus  to 
the  next  (or  previous)  scroll  bar  when  it  receives  a  Tab  or  Shift-Tab  keystroke.  It  calls  the 
old  scroll  bar  window  procedure  using  CallWindowProc. 

Coloring  the  Background 

When  COLORS1  defines  its  window  class,  it  gives  the  background  of  its  client  area  a  solid 
black  brush: 
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wndclass.hbrBackground  =  CreateSol idBrush  (0L)  ; 

When  you  change  the  settings  of  COLORSl’s  scroll  bars,  the  program  must  create  a  new 
brush  and  put  the  new  brush  handle  in  the  window  class  structure.  Just  as  we  were  able  to 
get  and  set  the  scroll  bar  window  procedure  using  GetWindowLong  and  SetWindowLong, 
we  can  get  and  set  the  handle  to  this  brush  using  GetClassWord  and  SetClassWord. 

You  can  create  the  new  brush  and  insert  the  handle  in  the  window  class  structure 
and  then  delete  the  old  brush: 

DeleteObject  (SetClassWord  (hwnd,  GCW_HBRBACKGROUND, 

CreateSolidBrush  (RGB  ( col  or [0] ,  col  or [1] ,  col or[2]))))  ; 

The  next  time  Windows  recolors  the  background  of  the  window,  Windows  will  use  this 
new  brush.  To  force  Windows  to  erase  the  background,  we  invalidate  the  entire  client  area: 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 

The  TRUE  (nonzero)  value  as  the  third  parameter  indicates  that  we  want  the  background 
erased  before  repainting. 

InvalidateRect  causes  Windows  to  put  a  WM_PAINT  message  in  the  message  queue 
of  the  window  procedure.  Because  WM_PAINT  messages  are  low  priority,  this  message 
will  not  be  processed  immediately  if  you  are  still  moving  the  scroll  bar  with  the  mouse  or 
the  cursor  keys.  Alternatively,  if  you  want  the  window  to  be  updated  immediately  after  the 
color  is  changed,  you  can  add  the  statement: 

UpdateWindow  (hwnd)  ; 

after  the  InvalidateRect  call.  But  this  slows  down  keyboard  and  mouse  processing. 

COLORSl’s  WndProc  function  doesn’t  process  the  WM_PAINT  message  but  passes  it 
to  DefWindowProc .  Window’s  default  processing  of  WM_PAINT  messages  simply  involves 
calling  BeginPaint  and  EndPaint  to  validate  the  window.  Because  we  specified  in  the  In¬ 
validateRect  call  that  the  background  should  be  erased,  the  BeginPaint  call  causes  Win¬ 
dows  to  generate  a  WM-ERASEBKGND  (erase  background)  message.  WndProc  ignores 
this  message  also.  Windows  processes  it  by  erasing  the  background  of  the  client  area  using 
the  brush  specified  in  the  window  class. 

Normally,  Windows  would  erase  the  entire  client  area  using  the  window  class  brush. 
Doing  so  would  erase  the  10  child  windows,  however,  and  Windows  would  then  have  to 
send  WM _PAINT  messages  to  all  the  child  windows  so  they  could  repaint  themselves — 
very  annoying.  We  avoid  the  problem  by  using  the  WS-CLIPCHILDREN  style  value  when 
first  creating  the  parent  window  using  CreateWindow\  this  style  prevents  the  parent  win¬ 
dow  from  painting  over  its  children.  Take  the  WS_CLIPCHILDREN  style  out  of  CreateWin- 
dow,  and  you’ll  see  a  big  difference  in  how  COLORS1  works. 
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Like  all  GDI  objects,  the  brushes  created  by  a  program  using  CreateSolidBrush  are 
not  automatically  deleted  by  Windows  when  the  program  terminates.  We’ve  been  good 
about  deleting  each  brush  before  creating  a  new  one,  but  when  the  program  is  about  to  ter¬ 
minate,  one  last  brush  in  the  window  class  still  should  be  discarded.  Thus,  during  process¬ 
ing  of  the  WM_DESTROY  message,  DeleteObject  is  called  once  more: 

Del eteObject  (SetCl assWord  (hwnd,  GCW.HBRBACKGROUND 
GetStockObject  ( WH I TE_B RUSH ) ) )  ; 


Coloring  the  Scroll  Bars 

On  a  color  display,  the  interiors  of  the  three  scroll  bars  in  COLORS1  are  red,  green,  and 
blue.  This  coloring  is  accomplished  by  processing  WM_CTLCOLOR  messages. 

In  WndProc  we  define  a  static  array  of  three  handles  to  brushes: 

static  HBRUSH  hBrush  [3]  ; 

During  processing  of  WM-CREATE,  we  create  the  three  brushes: 

hBrush [0]  =  CreateSolidBrush  (RGB  (255,  0.  0))  ; 

hBrushfl]  =  CreateSolidBrush  (RGB  (0,  255,  0))  ; 

hBrush[2]  =  CreateSolidBrush  (RGB  (0,  0,  255))  ; 

During  the  WM-CTLCOLOR  processing,  the  text  and  text  background  colors  are  set  to  the 

normal  values  for  scroll  bars.  The  brush  that’s  returned  from  this  message  is  one  of  the 
three  brushes  created  earlier: 

case  WM_CTLC0L0R  : 

if  (HI WORD  (lParam)  ==  CTLCO L0R_SC RO LLBAR ) 

{ 

SetBkCol or  (wParam,  GetSysColor  ( CO L0R_CAPT I ONTEXT ) )  ; 

SetTextColor  (wParam,  GetSysColor  ( C0L0R_W I NDOWFRAME ) )  ; 

n  =  GetWindowWord  ( LOWORD  (lParam),  GWW_ID)  ; 
point. x  =  point. y  =  0  ; 

ClientToScreen  (hwnd,  &point)  ; 

Unreal izeObject  ( hBrush [n] )  ; 

SetBrushOrg  (wParam,  point. x,  point. y)  ; 

return  ((DWORD)  hBrush[n] )  ; 

} 

break  ; 

These  brushes  must  be  destroyed  during  processing  of  the  WM -DESTROY  message: 
for  (n  =  0  ;  n  <  3  ;  DeleteObject  (hBrush  [n++]))  ; 
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Dealing  with  Multiple  Instances 

Normally,  Windows  programs  reuse  the  same  window  class  when  you  load  multiple  in¬ 
stances  of  the  program.  The  window  class  is  registered  only  if  the  previous  instance 
is  NULL: 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS_H REDRAW  !  CS_VREDRAW  ; 

[more program  lines] 

But  COLORS1  can’t  do  this,  because  the  background  color  is  specified  in  the  window  class. 
If  all  instances  of  COLORS1  used  the  same  window  class,  then  each  instance  would  use 
(and  change)  the  same  background  color.  We  can  avoid  this  problem  entirely  by  allowing 
only  one  instance  of  COLORS1  to  run: 

if  (hPrevInstance) 
return  FALSE  ; 

COLORS1  as  an  Icon 

When  you  make  COLORS1  into  an  icon,  the  entire  surface  of  the  icon — rather  than  only  the 
right  half — is  the  color  of  the  parent  window’s  background.  Yet  COLORS1  doesn’t  seem  to 
have  any  separate  icon  logic. 

You’ll  notice  that  COLORS1  specifies  a  NULL  icon  in  the  window  class: 
wndclass. hlcon  =  NULL  ; 

This  indicates  that  COLORS1  is  responsible  for  painting  its  icon.  The  entire  icon  appears  as 
the  background  color  because  Windows  hides  child  windows  when  a  program  becomes  an 
icon,  and  thus  the  colored  background  is  completely  uncovered. 


THE  EDIT  CLASS 

The  edit  class  is  in  some  ways  the  simplest  predefined  window  class  and  in  other  ways  the 
most  complex.  When  you  create  a  child  window  using  the  class  name  “edit,”  you  define 
a  rectangle  based  on  the  x  position,  y  position,  width,  and  height  parameters  of  the 
CreateWindow  cz\\.  This  rectangle  contains  editable  text.  When  the  child  window  control 
has  the  input  focus,  you  can  type  text,  move  the  cursor,  select  portions  of  text  using  either 
the  mouse  or  the  Shift  key  and  a  cursor  key,  delete  selected  text  to  the  clipboard  by  press¬ 
ing  Ctrl-X  or  Shift-Del,  or  insert  text  from  the  clipboard  by  pressing  Ctrl-V  or  Shift-Ins. 

One  of  the  simplest  uses  of  edit  controls  is  for  single-line  entry  fields.  For  instance, 
the  Windows  PIF  Editor  program  uses  edit  controls  in  this  way  on  its  main  window.  But 
edit  controls  are  not  limited  to  single  lines.  For  example,  the  Windows  Notepad  program 
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uses  a  multiline  edit  control.  The  file  size  of  the  Notepad  program  is  surprisingly  small — 
less  than  32  KB.  Most  of  the  editing  logic  is  not  in  Notepad  at  all;  it’s  in  the  edit  control  logic 
within  Windows. 

To  give  you  an  idea  of  the  power  of  edit  controls,  we’ll  write  a  “Notepad  clone”  pro¬ 
gram  called  POPPAD1.  We’ll  begin  the  program  in  this  chapter  and  continue  it  in  Chapters 
9  (when  we’ll  add  a  menu),  10  (when  we’ll  use  dialog  boxes  to  load  and  save  files),  and  15 
(when  it  will  print  files).  POPPAD1  is  shown  in  Figure  6-7. 

POPPAD1.MAK 


# . . 

#  P0PPAD1.MAK  make  file 

#  . 


poppadl.exe  :  poppadl.obj  poppadl.def 

$(WINLINK)  poppadl ,  poppadl,  NUL,  $(WINLIB),  poppadl.def 
rc  -t  poppadl.exe 

poppadl.obj  :  poppadl. c 
$ ( W I NCC )  poppadl. c 


POPPAD1.C 

/* . 

P0PPAD1.C  --  Popup  Editor  Using  Child  Window  Edit  Box 
(c)  Charles  Petzold,  1992 

. - . -*/ 


#include  <windows.h> 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 
char  szAppName[]  =  "PopPadl"  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


Figure  6-7.  The  POPPA D1  program.  (continued) 
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if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl  ass. hbrBackg round 
wndclass. IpszMenuName 
wndclass. IpszClassName 


CS_HREDRAW  !  CSJ/REDRAW  ; 
WndProc  ; 


hlnstance  ; 

Loadlcon  (NULL,  I DI_APPLI CATION )  ; 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHIT E_B RUSH)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  szAppName, 

WS_0V ERLAP P EDW I NDOW , 

CWJJSEDEFAULT,  CW_USEDEFAULT, 
GetSystemMetrics  (SM_CXSCREEN)  /  2, 
GetSystemMetrics  ( SM_CY SCREEN )  /  2, 

NULL,  NULL,  hlnstance.  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  ..export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HWND  hwndEdit  ; 


switch  (message) 

{ 

case  WM_CREATE: 

hwndEdit  =  CreateWindow  ("edit",  NULL, 

WS.CHILD  !  WS.VISIBLE  !  WS_HSCROLL  !  WS.VSCROLL  ! 
WS.BORDER  !  ES.LEFT  !  ES.MULTILINE  ! 
ES_AUT0HSCR0LL  !  ES.AUT0VSCR0LL, 

0,  0,  0,  0, 

hwnd,  1, 


(continued) 
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( ( LPCREATESTRUCT)  IParam)  ->  hlnstance,  NULL)  ; 

return  0  ; 

case  WM_SETFOCUS  : 

SetFocus  (hwndEdit)  ; 
return  0  ; 

case  WM.SIZE  : 

MoveWindow  (hwndEdit,  0,  0,  LOWORD  (IParam), 

HIWORD  (IParam),  TRUE)  ; 

return  0  ; 
case  WM.COMMAND  : 

if  (wParam  ==  1  &&  HIWORD  (IParam)  ==  EN.ERRSPACE) 
MessageBox  (hwnd,  "Edit  control  out  of  space.", 
szAppName,  MB_0K  !  MB_IC0NST0P)  ; 

return  0  ; 

case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


POPPAD1.DEF 


P0PPAD1.DEF  module  definition  file 


NAME 


P0PPAD1 


DESCRIPTION  'Popup  Editor  Version  1  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


POPPAD1  is  a  multiline  editor  (without  any  file  I/O  just  yet)  in  less  than  100  lines  of 
C.  As  you  can  see,  POPPAD1  itself  doesn’t  do  very  much.  The  predefined  edit  control  is 
doing  quite  a  lot.  In  this  form,  the  program  lets  you  explore  what  edit  controls  can  do  with¬ 
out  any  help  from  a  program. 
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The  Edit  Class  Styles 

As  noted  earlier,  you  create  an  edit  control  using  “edit”  as  the  window  class  in  the 
CreateWindow call.  The  window  style  is  WS-CHILD  plus  several  options.  As  in  static  child 
window  controls,  the  text  in  edit  controls  can  be  either  left-justified,  right-justified,  or 
centered.  You  specify  this  formatting  with  the  window  styles  ES-LEFT,  ES -RIGHT,  and 
ES-CENTER. 

By  default,  an  edit  control  has  a  single  line.  You  can  create  a  multiline  edit  control 
with  the  window  style  ES-MULTILINE.  For  a  single-line  edit  control,  you  can  normally  en¬ 
ter  text  only  to  the  end  of  the  edit  control  rectangle.  To  create  an  edit  control  that  automati¬ 
cally  scrolls  horizontally,  you  use  the  style  ES-AUTOHSCROLL.  For  a  multiline  edit  control, 
text  wordwraps  unless  you  use  the  ES_AUTOHSCROLL  style,  in  which  case  you  must  press 
the  Enter  key  to  start  a  new  line.  You  can  also  include  vertical  scrolling  in  a  multiline  edit 
control  by  using  the  style  ES_AUTOVSCROLL. 

When  you  include  these  scrolling  styles  in  multiline  edit  controls,  you  might  also 
want  to  add  scroll  bars  to  the  edit  control.  You  do  so  by  using  the  same  window  style  iden¬ 
tifiers  as  for  nonchild  windows:  WS_HSCROLL  and  WS-VSCROLL. 

By  default,  an  edit  control  does  not  have  a  border.  You  can  add  one  by  using  the  style 
WS -BORDER. 

When  you  select  text  in  an  edit  control,  Windows  displays  it  in  reverse  video.  When 
the  edit  control  loses  the  input  focus,  however,  the  selected  text  is  no  longer  highlighted.  If 
you  want  the  selection  to  be  highlighted  even  when  the  edit  control  does  not  have  the 
input  focus,  you  can  use  the  style  ES_NOHIDESEL. 

When  POPPAD1  creates  its  edit  control,  the  style  is  given  in  the  CreateWindow 
call  as: 

WS.CHILD  !  WS_V I S I B L E  !  WS.HSCROLL  !  WS_VSCROLL  ! 

WS.BORDER  i  ES_LE FT  !  ES_MULTI LINE  ! 

ES_AUT0HSCR0LL  !  ES_AUT0VSCR0LL 

In  POPPAD1  the  dimensions  of  the  edit  control  are  later  defined  by  a  call  to  MoveWindow 
when  WndProc  receives  a  WM_SIZE  message.  The  size  of  the  edit  control  is  simply  set  to 
the  size  of  the  main  window: 

MoveWindow  (hwndEdit,  0,  0,  LOWORD  (IParam), 

HIWORD  (IParam),  TRUE)  ; 

For  a  single-line  edit  control,  the  height  of  the  control  must  accommodate  the  height  of  a 
character.  If  the  edit  control  has  a  border  (as  most  do),  use  IV2  times  the  height  of  a  char¬ 
acter  (including  external  leading). 
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Edit  Control  Notification 

Edit  controls  send  WM -COMMAND  messages  to  the  parent  window  procedure.  The 
meanings  of  the  wParam  and  IParam  variables  are  the  same  as  for  button  controls: 


Parameter 

Description 

wParam 

Child  window  ID 

LOWORD  (IParam) 

Child  window  handle 

HIWORD  (IParam) 

Notification  code 

The  notification  codes  are  shown  below: 

EN-SETFOCUS 

Edit  control  has  gained  the  input  focus 

EN-KILLFOCUS 

Edit  control  has  lost  the  input  focus 

EN-CHANGE 

Edit  control’s  contents  will  change 

EN-UPDATE 

Edit  control’s  contents  have  changed 

EN_ERRSPACE 

Edit  control  has  run  out  of  space 

EN-MAXTEXT 

Edit  control  has  run  out  of  space  on  insertion 

EN-HSCROLL 

Edit  control’s  horizontal  scroll  bar  has  been  clicked 

EN-VSCROLL 

Edit  control’s  vertical  scroll  bar  has  been  clicked 

POPPAD1  traps  only  EN-ERRSPACE  notification  codes  and  displays  a  message  box. 

The  edit  control  stores  text  in  the  local  heap  of  its  parent  window’s  program.  The 
contents  of  an  edit  control  are  limited  to  about  32  KB.  You’ll  note  that  POPPAD1  reserves 
only  1  KB  of  space  for  its  local  heap  in  the  module  definition  file.  As  we’ll  see  in  Chapter  7, 
this  is  not  a  problem.  Windows  will  expand  the  program’s  local  heap  if  an  edit  control 
needs  more  space. 

Using  the  Edit  Controls 

If  you  use  several  single-line  edit  controls  on  the  surface  of  your  main  window  (as  PIFEDIT 
does),  you’ll  need  to  use  window  subclassing  to  move  the  input  focus  from  one  control  to 
another.  You  can  accomplish  this  much  as  COLORS1  does,  by  intercepting  Tab  and  Shift- 
Tab  keystrokes.  (Another  example  of  window  subclassing  is  shown  later  in  this  chapter  in 
the  HEAD  program.)  How  you  handle  the  Enter  key  is  up  to  you.  You  can  use  it  the  same 
way  as  the  Tab  key  or  as  a  signal  to  your  program  that  all  the  edit  fields  are  ready. 

If  you  want  to  insert  text  into  an  edit  field,  you  can  do  so  using  SetWindowText.  Get¬ 
ting  text  out  of  an  edit  control  involves  GetWindowTextLength  and  GetWindowText.  We’ll 
see  examples  of  these  facilities  in  our  later  revisions  to  the  POPPAD1  program. 
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Messages  to  an  Edit  Control 

We  won’t  cover  all  the  messages  you  can  send  to  an  edit  control  using  SendMessage , 
because  there  are  quite  a  few  of  them,  and  several  will  be  used  in  the  later  POPPAD  revi¬ 
sions.  Here’s  a  broad  overview. 

These  messages  let  you  cut,  copy,  or  clear  the  current  selection.  A  user  selects  the 
text  to  be  acted  upon  by  using  the  mouse  or  the  Shift  key  and  a  cursor  key,  thus  highlight¬ 
ing  the  selected  text  in  the  edit  control: 

SendMessage  (hwndEdit,  WM_CUT,  0,  0L)  ; 

SendMessage  (hwndEdit,  WM_C0PY,  0,  0L)  ; 

SendMessage  (hwndEdit,  WM_C LEAR ,  0,  0L)  ; 

WM-CUT  removes  the  current  selection  from  the  edit  control  and  sends  it  to  the  clipboard. 
WM_COPY  copies  the  selection  to  the  clipboard  but  leaves  it  intact  in  the  edit  control. 
WM_CLEAR  deletes  the  selection  from  the  edit  control  without  passing  it  to  the  clipboard. 
You  can  also  insert  clipboard  text  into  the  edit  control  at  the  cursor  position: 

SendMessage  (hwndEdit,  WM_PASTE,  0,  0L)  ; 

You  can  obtain  the  starting  and  ending  positions  of  the  current  selection: 

lSelect  =  SendMessage  (hwndEdit,  EM_GETSEL,  0,  0L) 

The  low  word  of  lSelect  has  the  starting  position.  The  high  word  has  the  end  position  plus  1. 
You  can  select  text: 

SendMessage  (hwndEdit,  EM_SETSEL,  0,  MAKELONG  (wBegin,  wEnd))  ; 

You  can  also  replace  a  current  selection  with  other  text: 

SendMessage  (hwndEdit,  EM_RE P LAC ES E L ,  0,  (LONG)  IpszString)  ; 

For  multiline  edit  controls,  you  can  obtain  the  number  of  lines: 

nCount  =  SendMessage  (hwndEdit,  EM_GETLI NECOUNT ,  0,  0L)  ; 

For  any  particular  line,  you  can  obtain  an  offset  from  the  beginning  of  the  edit  buffer  text: 

nOffset  =  SendMessage  (hwndEdit,  EM_LI NE I NDEX ,  wLine,  0L)  ; 

Lines  are  numbered  starting  at  0.  A  wLine  value  of-1  returns  the  offset  of  the  line  contain¬ 
ing  the  cursor.  You  obtain  the  length  of  the  line  from: 

nOffset  =  SendMessage  (hwndEdit,  EM.LINELENGTH,  wLine,  0L)  ; 

and  copy  the  line  itself  into  a  buffer  using: 

nLength  =  SendMessage  (hwndEdit,  EM_GETLINE,  wLine,  IpszBuffer)  ; 
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THE  LISTBOX  CLASS 

The  final  predefined  child  window  control  I’ll  discuss  in  this  chapter  is  the  list  box.  A  list 
box  is  a  collection  of  text  strings  displayed  as  a  scrollable  columnar  list  within  a  rectangle. 
A  program  can  add  or  remove  strings  in  the  list  by  sending  messages  to  the  list  box  window 
procedure.  The  list  box  control  sends  WM -COMMAND  messages  to  its  parent  window 
when  an  item  in  the  list  is  selected.  The  parent  window  can  then  determine  which  item  has 
been  selected. 

List  boxes  are  most  commonly  used  in  dialog  boxes  called  up  by  selecting  Open  from 
the  File  menu.  The  list  box  displays  files  in  the  current  directory  and  can  also  display  other 
subdirectories  and  disk  drives.  List  boxes  are  also  used  in  the  WRITE  program  for  selecting 
fonts.  A  list  box  can  be  either  single  selection  or  multiple  selection.  The  latter  allows  the 
user  to  select  more  than  one  item  from  the  list  box.  When  a  list  box  has  the  input  focus,  it 
displays  a  dashed  line  surrounding  an  item  in  the  list  box.  This  cursor  does  not  indicate  the 
selected  item  in  the  list  box.  The  selected  item  is  indicated  by  highlighting,  which  displays 
the  item  in  reverse  video. 

In  a  single-selection  list  box,  the  user  can  select  the  item  that  the  cursor  is  positioned 
on  by  pressing  the  Spacebar.  The  arrow  keys  move  both  the  cursor  and  the  current  selec¬ 
tion  and  can  scroll  the  contents  of  the  list  box.  The  Page  Up  and  Page  Down  keys  also  scroll 
the  list  box  by  moving  the  cursor  but  not  the  selection.  Pressing  a  letter  key  moves  the  cur¬ 
sor  and  the  selection  to  the  first  (or  next)  item  that  begins  with  that  letter.  An  item  can  also 
be  selected  by  clicking  or  double-clicking  the  mouse  on  the  item. 

In  a  multiple-selection  list  box,  the  Spacebar  toggles  the  selection  state  of  the  item 
where  the  cursor  is  positioned.  (If  the  item  is  already  selected,  it  is  deselected.)  The  arrow 
keys  deselect  all  previously  selected  items  and  move  the  cursor  and  selection  just  as  in 
single-selection  list  boxes.  However,  the  Ctrl  key  and  the  arrow  keys  can  move  the  cursor 
without  moving  the  selection.  The  Shift  key  and  arrow  keys  can  extend  a  selection. 

Clicking  or  double-clicking  an  item  in  a  multiple-selection  list  box  deselects  all  pre¬ 
viously  selected  items  and  selects  the  clicked  item.  However,  clicking  an  item  while  press¬ 
ing  the  Shift  key  toggles  the  selection  state  of  the  item  without  changing  the  selection  state 
of  any  other  item. 

List  Box  Styles 

You  create  a  list  box  child  window  control  with  CreateWindow  using  “listbox”  as  the  win¬ 
dow  class  and  WS -CHILD  as  the  window  style.  However,  this  default  list  box  style  does  not 
send  WM-COMMAND  messages  to  its  parent,  meaning  that  a  program  would  have  to  in¬ 
terrogate  the  list  box  (via  messages  to  the  list  box  controls)  regarding  the  selection  of  items 
within  the  list  box.  Therefore,  list  box  controls  almost  always  include  the  list  box  style 


253 


SECTION  II:  READING  INPUT 


identifier  LBS_NOTIFY,  which  allows  the  parent  window  to  receive  WM-COMMAND 
messages  from  the  list  box.  If  you  want  the  list  box  control  to  sort  the  items  in  the  list  box, 
you  can  also  use  LBS_SORT,  another  common  style. 

By  default,  list  boxes  are  single  selection.  Multiple-selection  list  boxes  are  relatively 
rare.  If  you  want  to  create  one,  you  use  the  style  LBS_MULTIPLESEL. 

Normally,  a  list  box  updates  itself  when  a  new  item  is  added  to  the  scroll  box  list.  You 
can  prevent  this  by  including  the  style  LBS_NOREDRAW.  You  will  probably  not  want  to 
use  this  style,  however.  Instead,  you  can  temporarily  prevent  repainting  of  a  list  box  con¬ 
trol  by  using  the  WM-SETREDRAW  message  that  I’ll  describe  a  little  later. 

By  default,  the  list  box  window  procedure  displays  only  the  list  of  items  without  any 
border  around  it.  You  can  add  a  border  with  the  window  style  identifier  WS -BORDER.  And 
to  add  a  vertical  scroll  bar  for  scrolling  through  the  list  with  the  mouse,  you  use  the  window 
style  identifier  WS-VSCROLL. 

WINDOWS.H  defines  a  list  box  style  called  LBS-STANDARD  that  includes  the  most 
commonly  used  styles.  It  is  defined  as: 

( LBS_N0TI FY  !  LBS.SORT  !  WS_VSCROLL  !  WS_B0RDER) 

You  can  also  use  the  WS-SIZEBOX  and  WS-CAPTION  identifiers,  but  these  will  allow  the 
user  to  resize  the  list  box  and  to  move  it  around  its  parent’s  client  area. 

The  width  of  a  list  box  should  accommodate  the  width  of  the  longest  string  plus  the 
width  of  the  scroll  bar.  You  can  get  the  width  of  the  vertical  scroll  bar  using: 

GetSystemMetrics  (SM_CXVSCROLL)  ; 

You  can  calculate  the  height  of  the  list  box  by  multiplying  the  height  of  a  character  by  the 
number  of  items  you  want  to  appear  in  view.  A  list  box  does  not  use  external  leading  when 
spacing  lines  of  text. 

Putting  Strings  in  the  List  Box 

After  you’ve  created  the  list  box,  the  next  step  is  to  put  text  strings  in  it.  You  do  this  by 
sending  messages  to  the  list  box  window  procedure  using  the  SendMessage  call.  The  text 
strings  are  generally  referenced  by  an  index  number  that  starts  at  0  for  the  topmost  item.  In 
the  examples  that  follow,  hwndList  is  the  handle  to  the  child  window  list  box  control,  and 
wlndex  is  the  index  value. 

In  cases  where  you  pass  a  text  string  in  the  SendMessage  call,  the  iParam  parameter 
is  a  far  pointer  to  a  null-terminated  string.  To  avoid  error  messages  during  compilation,  cast 
this  pointer  first  to  an  LPSTR  (long  pointer  to  a  string)  and  then  to  a  LONG. 

In  most  of  these  examples,  the  SendMessage  call  can  return  LB-ERRSPACE  (defined 
as  -2)  if  the  window  procedure  runs  out  of  available  memory  space  to  store  the  contents  of 
the  list  box.  SendMessage  returns  LB_ERR  (-1)  if  an  error  occurs  for  other  reasons  and 
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LB-OKAY  (0)  if  the  operation  is  successful.  You  can  test  SendMessage  for  a  nonzero  value 
to  detect  either  of  the  two  errors.  The  list  box  allocates  global  memory  (outside  your  pro¬ 
gram’s  data  segment)  for  the  list  box  contents. 

If  you  use  the  LBS_SORT  style  (or  if  you  are  placing  strings  in  the  list  box  in  the  order 
that  you  want  them  to  appear),  then  the  easiest  way  to  fill  up  a  list  box  is  with  the  LB- 
_ADDSTRING  message: 

SendMessage  (hwndList.  LB.ADDSTRING,  0,  (LONG)  ( LPSTR)  szString)  ; 

If  you  do  not  use  LBS -SORT,  you  can  insert  strings  into  your  list  box  by  specifying  an  index 
value  with  LB_INSERTSTRING: 

SendMessage  (hwndList,  LB_I NSERTSTRI NG ,  wlndex,  (LONG)  (LPSTR)  szString)  ; 

For  instance,  if  wlndex  is  equal  to  4,  szString  becomes  the  new  string  with  an  index  value 
of  4 — the  fifth  string  from  the  top  because  counting  starts  at  0.  Any  strings  below  this  point 
are  pushed  down.  A  wlndex  value  of-1  adds  the  string  to  the  bottom.  You  can  use  LB -IN¬ 
SERTSTRING  with  list  boxes  that  have  the  LBS-SORT  style,  but  the  list  box  contents  will 
not  be  re-sorted.  (You  can  also  insert  strings  into  a  list  box  using  the  LB_DIR  message, 
which  is  discussed  in  detail  toward  the  end  of  this  chapter.) 

You  can  delete  a  string  from  the  list  box  by  specifying  the  index  value  with  the 
LB-DELETESTRING  message: 

SendMessage  (hwndList,  LB_DELETESTRING,  wlndex,  0L)  ; 

You  can  clear  out  the  list  box  using  LB-RESETCONTENT: 

SendMessage  (hwndList,  LB_RES ETCONTENT ,  0,  0L)  ; 

The  list  box  window  procedure  updates  the  display  when  an  item  is  added  to  or  de¬ 
leted  from  the  list  box.  If  you  have  a  number  of  strings  to  add  or  delete,  you  may  want  to 
temporarily  inhibit  this  action  by  turning  off  the  control’s  redraw  flag: 

SendMessage  (hwndList,  WM_SETREDRAW,  FALSE,  0L)  ; 

After  you’ve  finished,  you  can  turn  the  redraw  flag  back  on: 

SendMessage  (hwndList,  WM_SETREDRAW,  TRUE,  0L)  ; 

A  list  box  created  with  the  LBS-NOREDRAW  style  begins  with  the  redraw  flag  turned  off. 

Selecting  and  Extracting  Entries 

The  SendMessage  calls  that  carry  out  the  tasks  shown  below  usually  return  a  value.  If  an 
error  occurs,  this  value  is  set  to  LB_ERR  (defined  as  -1).  Note  that  the  return  value  from 
SendMessage  is  normally  a  signed  long  (LONG),  but  the  values  are  unsigned  integers 
(WORD),  so  some  casting  is  necessary. 
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After  you’ve  put  some  items  into  a  list  box,  you  can  find  out  how  many  items  are  in 
the  list  box: 

nCount  =  (WORD)  SendMessage  (hwndList,  LB_GETCOUNT,  0,  0L)  ; 

Some  of  the  other  calls  are  different  for  single-selection  and  multiple-selection  list 
boxes.  Let’s  first  look  at  single-selection  list  boxes. 

Normally,  you’ll  let  a  user  select  from  a  list  box.  But  if  you  want  to  highlight  a  default 
selection,  you  can  use: 

SendMessage  (hwndList,  LB_SETCURSEL,  nlndex,  0L)  ; 

Setting  wParam  to  -1  in  this  call  deselects  all  items. 

You  can  also  select  an  item  based  on  its  initial  characters: 

nlndex  =  (WORD)  SendMessage  (hwndList,  LB_S E LECTSTRI NG ,  wlndex, 

(LONG)  ( LPSTR)  szSearchStri ng )  ; 

The  wlndex  given  as  the  wParam  parameter  to  the  SendMessage  call  is  the  index  following 
which  the  search  begins  for  an  item  with  initial  characters  that  match  szSearchString.  A 
wlndex  value  of-1  starts  the  search  from  the  top.  SendMessage  returns  the  index  of  the  se¬ 
lected  item,  or  LB_ERR  if  no  initial  characters  match  szSearchString. 

When  you  get  a  WM-COMMAND  message  from  the  list  box  (or  at  any  other  time), 
you  can  determine  the  index  of  the  current  selection  using  LB_GETCURSEL: 

nlndex  =  (WORD)  SendMessage  (hwndList,  LB.GETCURSEL,  0,  0L)  ; 

The  nlndex  value  returned  from  the  call  is  LB_ERR  if  no  item  is  selected. 

You  can  determine  the  length  of  any  string  in  the  list  box: 

nLength  =  (WORD)  SendMessage  (hwndList,  LB_GETTEXTLEN,  nlndex,  0L)  ; 

and  copy  the  item  into  the  text  buffer: 

nLength  =  (WORD)  SendMessage  (hwndList,  LB_GETTEXT,  nlndex, 

(LONG)  (LPSTR)  szBuffer)  ; 

In  both  cases,  the  nLength  value  returned  from  the  call  is  the  length  of  the  string.  The 
szBuffer  array  must  be  large  enough  for  the  length  of  the  string  and  a  terminating  NULL. 
You  may  want  to  use  LB_GETTEXTLEN  to  first  allocate  some  local  memory  to  hold  the 
string  (which  you’ll  learn  how  to  do  in  Chapter  8). 

For  a  multiple-selection  list  box,  you  cannot  use  LB_SETCURSEL,  LB_GETCURSEL, 
or  LB_SELECTSTRING.  Instead,  you  use  LB_SETSEL  to  set  the  selection  state  of  a  particu¬ 
lar  item  without  affecting  other  items  that  may  also  be  selected: 

SendMessage  (hwndList,  LB_SETSEL,  wParam,  (LONG)  wlndex)  ; 

The  wParam  parameter  is  nonzero  to  select  and  highlight  the  item  and  0  to  deselect  it.  If 
the  iParam  parameter  is  -1,  all  items  are  either  selected  or  deselected.  You  can  also  deter¬ 
mine  the  selection  state  of  a  particular  item  using: 
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wSelect  =  (WORD)  SendMessage  (hwndList,  LB_GETSEL,  wlndex,  0L)  ; 
where  wSelect  is  set  to  nonzero  if  the  item  indexed  by  wlndex  is  selected  and  0  if  it  is  not. 

Receiving  Messages  from  List  Boxes 

When  a  user  clicks  on  a  list  box  with  the  mouse,  the  list  box  receives  the  input  focus.  A 
parent  window  can  give  the  input  focus  to  a  list  box  control  by  using: 

SetFocus  (hwndList)  ; 

When  a  list  box  has  the  input  focus,  the  cursor  movement  keys,  letter  keys,  and  Spacebar 
can  also  be  used  to  select  items  from  the  list  box. 

A  list  box  control  sends  WM -COMMAND  messages  to  its  parent.  The  meanings  of 
the  wParam  and  IParam  variables  are  the  same  as  for  the  button  and  edit  controls: 

wParam  Child  window  ID 

LOWORD  (IParam)  Child  window  handle 

HI  WORD  ( IParam )  Notification  code 

The  notification  codes  and  their  values  are  as  follows: 

LBN-ERRSPACE  -2 

LBN-SELCHANGE  1 

LBN-DBLCLK  2 

LBN-SELCANCEL  3 

LBN-SETFOCUS  4 

LBN-KILLFOCUS  5 

The  list  box  control  sends  the  parent  window  LBN_SELCHANGE  and  LBN_DBLCLK  codes 
only  if  the  list  box  window  style  includes  LBS -NOTIFY. 

The  LBN_ERRSPACE  code  indicates  that  the  list  box  control  has  run  out  of  space.  The 
LBN_SELCHANGE  code  indicates  that  the  current  selection  has  changed;  these  messages 
occur  as  the  user  moves  the  highlight  through  the  list  box,  toggles  the  selection  state  with 
the  Spacebar,  or  clicks  an  item  with  the  mouse.  The  LBN_DBLCLK  code  indicates  that  a  list 
box  item  has  been  double-clicked  with  the  mouse.  (The  notification  code  values  for 
LBN_SELCHANGE  and  LBN_DBLCLK  refer  to  the  number  of  mouse  clicks.) 

Depending  on  your  application,  you  may  want  to  use  either  LBN_SELCHANGE  or 
LBN_DBLCLK  messages  or  both.  Your  program  will  get  many  LBN_SELCHANGE  mes¬ 
sages,  but  LBN_DBLCLK  messages  occur  only  when  the  user  double-clicks  with  the  mouse. 
If  your  program  uses  double-clicks,  you’ll  need  to  provide  a  keyboard  interface  that  dupli¬ 
cates  LBN_DBLCLK. 
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A  Simple  List  Box  Application 

Now  that  you  know  how  to  create  a  list  box,  fill  it  with  text  items,  receive  messages  from 
the  list  box,  and  extract  strings,  it’s  time  to  program  an  application.  The  ENVIRON  pro¬ 
gram,  shown  in  Figure  6-8,  uses  a  list  box  in  its  client  area  to  display  the  name  of  your  cur¬ 
rent  MS-DOS  environment  variables  (such  as  PATH,  COMSPEC,  and  PROMPT).  As  you 
select  a  variable,  the  name  and  the  environment  string  are  displayed  across  the  top  of  the 
client  area. 

ENVIRON. MAK 

# 

//  ENVIRON. MAK  make  file 
# . 

env1ron.exe  :  environ. obj  environ. def 

$(WINLINK)  environ,  environ,  NUL,  $(WINLIB),  environ 
rc  -t  envi ron.exe 

environ. obj  :  environ.c 
$ ( W I NCC )  environ.c 


ENVIRON.C 

/*- .  . 

ENVIRON.C  --  Environment  List  Box 

(c)  Charles  Petzold,  1992 
. */ 


//include  <windows.h> 

//include  <stdlib.h> 

//include  <string.h> 

//define  MAXENV  4096 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Environ"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


Figure  6-8.  The  ENVIRON  program. 


(continued) 


258 


Chapter  6:  Child  Window  Controls 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass.lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. lpszMenuName 
wndclass.lpszClassName 


CS.HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  I DI_APP LI CATION )  ; 
LoadCursor  (NULL,  IDC.ARR0W)  ; 
C0L0R_WI NDOW  +  1  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 

} 


hwnd  =  CreateWindow  (szAppName,  "Environment  List  Box”, 
WS_OVERLAPPEDWINDOW, 

CWJJSEDEFAULT,  CW_USEDEFAULT, 
CW_USEDEFAULT,  CW_USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 
{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  char  szBuffer  [MAXENV  +  1]  ; 
static  HWND  hwndList,  hwndText  ; 

HDC  hdc  ; 

TEXTMETRIC  tm  ; 

WORD  n  ; 


switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 
GetTextMetrics  (hdc,  &tm)  ; 
ReleaseDC  (hwnd,  hdc)  ; 


hwndList  =  CreateWindow  ("listbox",  NULL, 

W S_C H I L D  !  WSJ/ISIBLE  !  LBS_STANDARD, 


(continued) 
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tm.tmAveCharWidth,  tm. tmHeight  *  3, 
tm.tmAveCharWidth  *  16  + 

GetSystemMetrics  ( SM_CX VSCROLL ) , 
tm. tmHeight  *  5, 
hwnd,  1, 

GetWindowWord  (hwnd,  GWW_H INSTANCE) ,  NULL)  ; 

hwndText  =  CreateWindow  ("static",  NULL, 

WS.CHILD  !  WS_V I S I B LE  !  SS_LE FT , 
tm.tmAveCharWidth,  tm. tmHeight, 

tm.tmAveCharWidth  *  MAXENV,  tm. tmHeight, 
hwnd,  2, 

GetWindowWord  (hwnd,  GWW_H I NSTANCE ) ,  NULL)  ; 

for  (n  =  0  ;  environ[n]  ;  n++) 

{ 

if  (strlen  (environ  [n] )  >  MAXENV) 
continue  ; 

*strchr  (strcpy  (szBuffer,  environ  [n]),  '  =  ')  =  ' \0 '  ; 
SendMessage  (hwndList,  LB_ADDSTRING,  0, 

(LONG)  ( LPSTR)  szBuffer)  ; 

} 

return  0  ; 

case  WM_SETFOCUS  : 

SetFocus  (hwndList)  ; 
return  0  ; 

case  WM_COMMAND  : 

if  (wParam  ==  1  &&  HIWORD  (IParam)  ==  LBN_SE LCHANGE ) 

{ 

n  =  (WORD)  SendMessage  (hwndList,  LB.GETCURSEL,  0,  0L) 
n  =  (WORD)  SendMessage  (hwndList,  LB.GETTEXT,  n, 

(LONG)  (LPSTR)  szBuffer)  ; 

strcpy  (szBuffer  +  n  +  1,  getenv  (szBuffer))  ; 
*(szBuffer  +  n)  =  '='  ; 

SetWindowText  (hwndText,  szBuffer)  ; 

} 

return  0  ; 

case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
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ENVIRON.DEF 


ENVIRON. DEF  module  definition  file 


NAME  ENVIRON 

DESCRIPTION  'Environment  List  Box  Program  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 

ENVIRON  creates  two  child  windows:  a  list  box  with  the  style  LBS_STANDARD 
and  a  static  window  with  the  style  SS-LEFT  (left-justified  text).  ENVIRON  uses  the  envi¬ 
ron  variable  (declared  external  in  STDLIB.H)  to  obtain  the  list  of  environment  strings,  and 
it  uses  the  message  LB_ADDSTRING  to  direct  the  list  box  window  procedure  to  place  each 
string  in  the  list  box. 

When  you  run  ENVIRON,  you  can  select  an  environment  variable  using  the  mouse  or 
the  keyboard.  Each  time  you  change  the  selection,  the  list  box  sends  a  WM_COMMAND 
message  to  the  parent  window,  which  is  WndProc.  When  WndProc  receives  a  WM_COM- 
MAND  message,  it  checks  to  see  if  wParam  is  1  (the  child  ID  of  the  list  box)  and  if  the  high 
word  of  iParam  (the  notification  code)  is  equal  to  LBN_SELCHANGE.  If  so,  it  obtains  the 
index  of  the  selection  using  the  LB_GETCURSEL  message  and  the  text  itself — the  environ¬ 
ment  variable  name — using  LB_GETTEXT.  The  ENVIRON  program  uses  the  C  function 
getenv  to  obtain  the  environment  string  corresponding  to  that  variable  and  SetWindowText 
to  pass  this  string  to  the  static  child  window  control,  which  displays  the  text. 

Note  that  ENVIRON  cannot  use  the  index  returned  from  LB_GETCURSEL  to  index 
the  environ  variable  and  obtain  the  environment  string.  Because  the  list  box  has  an 
LBS-SORT  style  (included  in  LBS-STANDARD),  the  indices  no  longer  match. 


Listing  Files 

I’ve  been  saving  the  best  for  last:  LB_DIR,  the  most  powerful  list  box  message.  This  fills  the 
list  box  with  a  file  directory  list,  optionally  including  subdirectories  and  valid  disk  drives: 

SendMessage  (hwndList,  LB_DIR,  wAttr,  (LONG)  (LPSTR)  1 pszFi 1 eSpec)  ; 

Using  file  attribute  codes 

The  wAttr  parameter  is  a  file  attribute  code.  The  least  significant  byte  is  the  normal  file 
attribute  code  when  making  MS-DOS  function  calls: 
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wAttr 

Attribute 

0x0000 

Normal  file 

0x0001 

Read-only  file 

0x0002 

Hidden  file 

0x0004 

System  file 

0x0010 

Subdirectory 

0x0020 

File  with  archive  bit  set 

The  high  byte  provides  some  additional  control  over  the  items  desired: 

wAttr 

Option 

0x4000 

Include  drive  letters 

0x8000 

Exclusive  search  only 

When  the  wAttr  value  of  the  LB_DIR  message  is  0x0000,  the  list  box  lists  normal 
files,  read-only  files,  and  files  with  the  archive  bit  set.  This  is  consistent  with  the  logic  used 
by  MS-DOS  function  calls  to  find  files.  When  the  value  is  0x0010,  the  list  includes  child 
subdirectories  in  addition  to  these  files;  this  list  is  the  equivalent  of  that  displayed  by  the 
Directory  command  or  by  Windows’  File  Manager.  A  value  of  0x4010  expands  the  0x0010 
list  to  include  all  valid  drives;  for  many  Windows  programs,  this  is  the  list  in  the  dialog  box 
called  up  by  selecting  Open  from  the  program’s  File  menu.  To  list  all  files,  child  subdirec¬ 
tories,  and  drives,  you  set  the  wAttr  value  to  0x4037. 

Setting  the  topmost  bit  of  wAttr  lists  the  files  with  the  indicated  flag  while  excluding 
normal  files.  For  a  Windows  file  backup  program,  for  instance,  you  might  want  to  list  only 
files  that  have  been  modified  since  the  last  backup.  Such  files  have  their  archive  bits  set,  so 
you  would  use  0x8020.  A  value  of  0x8010  lists  only  subdirectories;  OxCOOO,  only  valid  disk 
drives;  and  OxCOlO,  subdirectories  and  valid  disk  drives  but  no  files. 

Ordering  file  lists 

The  iParam  parameter  is  a  far  pointer  to  a  file  specification  string  such  as  This  file 
specification  does  not  affect  the  subdirectories  that  the  list  box  includes. 

You’ll  want  to  use  the  LBS_SORT  message  for  list  boxes  with  file  lists.  The  list  box 
will  first  list  files  satisfying  the  file  specification  and  then  (optionally)  list  valid  disk  drives 
in  the  form: 

[  "A-  ] 

and  (also  optionally)  subdirectory  names.  The  first  subdirectory  listing  will  take  the  form: 

[..] 


262 


Chapter  6:  Child  Window  Controls 


This  “double-dot”  subdirectory  entry  lets  the  user  back  up  one  level  toward  the  root  direc¬ 
tory.  (The  entry  will  not  appear  if  you’re  listing  files  in  the  root  directory.)  Finally,  the 
specific  subdirectory  names  are  listed  in  the  form: 

[SUBDIR] 

If  you  do  not  use  LBS_SORT,  the  filenames  and  subdirectory  names  are  intermixed  and  the 
drive  letters  appear  at  the  bottom  of  the  list  box. 

A  head  for  Windows 

A  well-known  UNIX  utility  called  head  displays  the  beginning  lines  of  a  file.  Let’s  use  a  list 
box  to  write  a  similar  program  for  Windows.  HEAD,  shown  in  Figure  6-9,  lists  all  files  and 
child  subdirectories  in  the  li*st  box.  You  can  choose  a  file  to  display  by  double-clicking  on 
the  filename  with  the  mouse  or  by  pressing  the  Enter  key  when  the  filename  is  selected. 
You  can  also  change  the  subdirectory  using  either  of  these  methods.  The  program  displays 
up  to  8  KB  of  the  beginning  of  the  file  in  the  right  side  of  the  client  area  of  HEAD’S  window. 

HEAD.MAK 

#■■ . - . 

#  HEAD.MAK  make  file 

#■ . . 


head.exe  :  head.obj  head.def 

S(WINLINK)  head,  head,  NUL,  $(WINLIB),  head 
rc  -t  head.exe 

head.obj  :  head.c 
$ ( W I NCC )  head.c 


HEAD.C 


/* 


HEAD.C  --  Displays  Beginning  (Head)  of  File 
(c)  Charles  Petzold,  1992 


*/ 


#include  <windows.h> 

#include  <string.h> 

#include  <direct.h> 

#define  MAXPATH  80 
#define  MAXREAD  8192 

Figure  6-9.  The  HEAD  program.  (continued) 
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long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT.  LONG)  ; 
long  FAR  PASCAL  .export  ListProc  (HWND,  UINT,  UINT,  LONG)  ; 


FARPROC  IpfnOldList  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "Head”  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( ! hPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbCl sExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. IpszMenuName 
wndclass. 1 pszCl assName 


CS.HREDRAW  !  CS.VREDRAW  ; 
WndProc  ; 


hlnstance  ; 

Loadlcon  (NULL,  I D I.APPLI CATI ON )  ; 
LoadCursor  (NULL,  IDC.ARR0W)  ; 
C0L0R.W I NDOW  +  1  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "File  Head", 

WS.O V ERLAPP EDW I NDOW  !  WS.C L I PCH I LDREN , 
CW.USEDEFAULT,  CW.USEDEFAULT, 

CW.US EDEFAU LT ,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 
{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


{ 


(continued) 
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static  BOOL 
static  char 
static  char 
static  HWND 
static  OFSTRUCT 
static  RECT 
char 
HDC 
int 

PAINTSTRUCT 

TEXTMETRIC 


bValidFile  ; 
sReadBuffer  [MAXREAD]  ; 
szFile  [16]  ; 
hwndList,  hwndText  ; 
ofs  ; 
rect  ; 

szBuffer  [MAXPATH  +  1]  ; 
hdc  ; 

iHandle,  i  ; 
ps  ; 
tm  ; 


switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 
GetTextMetrics  (hdc,  &tm)  ; 

ReleaseDC  (hwnd,  hdc)  ; 


rect. left  =  20  *  tm. tmAveCharWidth  ; 
rect. top  =  3  *  tm.tmHeight  ; 

hwndList  =  CreateWindow  ("listbox",  NULL, 

WS_CHI LDWINDOW  !  WS.VISIBLE  !  LBS_STANDARD, 
tm. tmAveCharWidth,  tm.tmHeight  *  3, 
tm. tmAveCharWidth  *  13  + 

GetSystemMetrics  (SM_CXVSCROLL) , 
tm.tmHeight  *  10, 
hwnd,  1, 

GetWindowWord  (hwnd,  GWW_H I NSTANCE ) ,  NULL)  ; 

hwndText  =  CreateWindow  ("static",  getcwd  (szBuffer,  MAXPATH), 
WS_CH I LDW I N DOW  !  WSJ/ISIBLE  !  SS_LE FT , 
tm. tmAveCharWidth,  tm.tmHeight, 

tm. tmAveCharWidth  *  MAXPATH,  tm.tmHeight, 
hwnd,  2, 

GetWindowWord  (hwnd,  GWW_H I NSTANCE ) ,  NULL)  ; 


lpfnOldList  =  (FARPROC)  GetWi ndowLong  (hwndList,  GWLJINDPROC)  ; 

SetWindowLong  (hwndList,  GWL_WNDPROC, 

(LONG)  MakeProcInstance  ((FARPROC)  ListProc, 

GetWindowWord  (hwnd,  GWW_HI NSTANCE ) ) )  ; 


SendMessage  (hwndList,  LB.DIR,  0x37,  (LONG)  ( LPSTR)  "*.*")  ; 
return  0  ; 

case  WM_SIZE  : 

rect. right  =  LOWORD  (IParam)  ; 
rect. bottom  =  HIWORD  (IParam)  ; 
return  0  ; 


(continued) 
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case  WM.SETFOCUS  : 

SetFocus  (hwndList)  ; 
return  0  ; 

case  WM.COMMAND  : 

if  (wParam  ==  1  &&  HIWORD  (IParam)  ==  LBN.DBLCLK) 

{ 

if  (LB_ERR  ==  (i  =  (WORD)  SendMessage  (hwndList, 

LB_GETCURSEL,  0,  0L))) 

break  ; 

SendMessage  (hwndList,  LB_GETTEXT,  i, 

( L0N3)  (char  far  *)  szBuffer)  ; 

if  (-1  !=  OpenFile  (szBuffer.  &ofs,  0F_EXIST  !  0F_READ) ) 

{ 

bValidFile  =  TRUE  ; 
strcpy  (szFile,  szBuffer)  ; 
getcwd  (szBuffer,  MAXPATH)  ; 
if  (szBuffer  [strlen  (szBuffer)  -  1]  !=  '\\') 
strcat  (szBuffer,  "\\")  ; 

SetWindowText  (hwndText,  strcat  (szBuffer,  szFile))  ; 
} 

else 

{ 

bValidFile  =  FALSE  ; 

szBuffer  [strlen  (szBuffer)  -  1]  =  * \0 '  ; 
chdir  (szBuffer  +  1)  ; 
getcwd  (szBuffer,  MAXPATH)  ; 

SetWindowText  (hwndText,  szBuffer)  ; 

SendMessage  (hwndList,  LB.RESETCONTENT,  0,  0L)  ; 
SendMessage  (hwndList,  LB_DIR,  0x37, 

(LONG)  ( LPSTR)  "*.*")  ; 

} 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 

} 

return  0  ; 
case  WM_PA I  NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 
SetTextCol or  (hdc.  GetSysColor  ( C0L0R_W I NDOWTEXT ) )  ; 

SetBkCol or  (hdc.  GetSysColor  ( C0L0R_WI NDOW ) )  ; 

if  (bValidFile  &&  -1  !=  (iHandle  = 

OpenFile  (szFile,  &ofs,  OF.REOPEN  !  0F_READ) ) ) 

{ 

i  =  Jread  (iHandle,  sReadBuffer,  MAXREAD)  ; 

_1 cl ose  (iHandle)  ; 

DrawText  (hdc,  sReadBuffer,  i,  &rect,  DT_WORDBREAK  ! 

DT.EXPANDTABS  !  DOOCLIP  !  DT.NOPREFIX)  ; 


(continued) 
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} 

else 

bValidFile  =  FALSE  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

long  FAR  PASCAL  ^export  ListProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

if  (message  ==  WM_KEY DOWN  &&  wParam  ==  VK_RETURN) 

SendMessage  (GetParent  (hwnd),  WM_COMMAND,  1, 

MAKELONG  (hwnd,  LBN_DBLCLK) )  ; 

return  CallWindowProc  (1 pfnOl dList,  hwnd,  message,  wParam,  IParam)  ; 

} 


HEAD.DEF 


HEAD.DEF  module  definition  file 


NAME  HEAD 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'File  Head  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


In  ENVIRON,  when  we  selected  an  environment  variable — either  with  a  mouse  click 
or  with  the  keyboard — the  program  displayed  an  environment  string.  If  we  used  this 
select-display  approach  in  HEAD,  however,  the  program  would  be  too  slow  because  it 
would  continually  need  to  open  and  close  files  as  you  moved  the  selection  through  the  list 
box.  Instead,  HEAD  requires  that  the  file  or  subdirectory  be  double-clicked.  This  presents 
a  bit  of  a  problem  because  list  box  controls  have  no  automatic  keyboard  interface  that 
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corresponds  to  a  mouse  double-click.  As  we  know,  we  should  provide  keyboard  interfaces 
when  possible. 

The  solution?  Window  subclassing,  of  course.  The  list  box  subclass  function  in  HEAD 
is  called  ListProc.  It  simply  looks  for  a  WM_KEYDOWN  message  with  wParam  equal  to 
VK-RETURN  and  sends  a  WM_COMMAND  message  with  an  LBN-DBLCLK  notification 
code  back  to  the  parent.  The  WM -COMMAND  processing  in  WndProc  uses  the  Windows 
function  OpenFile  to  check  for  the  selection  from  the  list.  If  OpenFile  returns  an  error,  the 
selection  is  not  a  file,  so  it’s  probably  a  subdirectory.  HEAD  then  uses  chdir  to  change  the 
subdirectory.  It  sends  an  LB-RESETCONTENT  message  to  the  list  box  to  clear  out  the  con¬ 
tents  and  an  LB_DIR  message  to  fill  the  list  box  with  files  from  the  new  subdirectory. 

The  WM-PAINT  message  processing  in  WndProc  opens  the  file  using  the  Win¬ 
dows  OpenFile  function.  This  returns  an  MS-DOS  handle  to  the  file  that  can  be  passed  to 
the  Windows  functions  _lread  and  _ Iclose .  The  contents  of  the  file  are  displayed  using 
DrawText. 

8  KB  of  Wasted  Space 

HEAD  includes  an  8-KB  array  called  sReadBuffer  that  is  needed  only  briefly,  when  the 
contents  of  the  file  are  read  and  passed  to  DrawText.  But  this  array  remains  in  the  pro¬ 
gram’s  data  segment  during  the  entire  time  this  program  is  running.  Wouldn’t  it  make  more 
sense  to  allocate  that  memory  before  the  _ Iread  call  and  free  it  up  after  DrawText ? 

Yes,  it  would.  For  that  reason  we  can  no  longer  avoid  the  subject  of  Windows  memory 
management.  It’s  not  an  easy  subject,  but  let’s  begin. 
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USING 

RESOURCES 


CHAPTER  7 


Memory 

Management 


Multitasking  without  memory  management  is  like  having  a  party  in  a  closet:  You  may  be 
able  to  accommodate  some  of  the  earlier  arrivals,  but  once  everybody  starts  mingling, 
some  toes  are  going  to  get  smashed. 

Programs  always  require  memory.  A  program’s  code  must  reside  in  memory,  a  pro¬ 
gram’s  data  must  reside  in  memory,  and  during  execution  the  program  may  need  to  allo¬ 
cate  more  memory.  Even  in  a  single-tasking  environment,  as  a  program  allocates  and  frees 
memory,  memory  can  become  fragmented.  A  memory  allocation  request  could  fail  if  the 
contiguous  free  memory  is  insufficient  to  satisfy  the  request,  even  if  the  total  amount  of  free 
memory  is  plentiful.  The  situation  can  get  much  worse  in  a  multitasking  environment. 

To  avoid  these  problems,  an  operating  system  that  adequately  manages  memory  at 
the  very  least  must  be  able  to  move  blocks  of  memory  to  consolidate  free  memory  space. 
Sometimes  this  can  be  transparent  to  the  application,  and  sometimes  not.  Much  of  this 
chapter  concerns  dealing  with  memory  movement  when  it  isn’t  so  transparent. 

Memory  management  has  always  been  one  of  the  most  remarkable  aspects  of  Win¬ 
dows.  Even  Windows  1.0 — which  used  only  the  640  KB  of  memory  available  on  Intel  8088 
machines  and  286  machines  running  in  real  mode — included  a  sophisticated  memory 
management  scheme  that  implemented  in  software  some  of  the  memory  management  fea¬ 
tures  you  might  expect  to  find  in  a  protected  mode  operating  system.  Here  are  some  fea¬ 
tures  of  Windows  1.0  memory  management: 
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■  When  Windows  1.0  ran  multiple  instances  of  the  same  program,  it  used 
the  same  code  segments  and  the  same  resources  for  each  instance. 
(Resources  include  icons,  cursors,  menu  templates,  and  dialog  box 
templates,  all  of  which  are  covered  in  the  next  three  chapters.)  In  most 
cases,  Windows  required  only  that  data  segments  be  unique  for  each 
instance  of  a  program. 

■  Much  of  the  memory  allocated  within  Windows  was  moveable,  including 
(in  most  cases)  the  memory  allocated  for  a  program’s  code  segments,  data 
segments,  and  resources. 

■  Code  segments  and  resources  were  often  “demand  loaded” — that  is, 
Windows  did  not  load  them  into  memory  until  a  program  specifically 
needed  them. 

■  Code  segments  and  resources  were  often  discardable:  When  Windows 
needed  to  free  some  memory,  it  discarded  the  segments  from  memory  and 
later  reloaded  them  from  the  program’s  .EXE  file  as  the  program  required. 

These  memory  management  features  allowed  Windows  1.0  to  run  several  large  pro¬ 
grams  in  a  memory  space  that  might  not  be  large  enough  for  even  one  of  the  programs 
under  a  less  ambitious  memory  management  scheme.  The  problem  is  that  actual  memory 
was  limited  to  640  KB.  This  memory  management  scheme  required  that  Windows  often 
reload  code  segments  and  resources  from  the  hard  disk,  which  hurt  program  performance. 
For  this  reason,  support  of  the  bank-switched  memory  defined  by  the  Lotus-Intel- 
Microsoft  Expanded  Memory  Specification  (LIM  EMS)  4.0  was  added  to  Windows  2.1,  and 
protected  mode  support  was  added  to  Windows  3.0. 

Windows  3.0  runs  in  three  distinct  modes: 

■  On  a  machine  based  around  the  Intel  8086  processor  (or  a  286  or  386 
processor  with  less  than  1  MB  of  memory),  Windows  3.0  runs  in  “real 
mode.”  This  is  essentially  compatible  with  the  memory  configuration  of 
Windows  2.1.  Windows  and  its  applications  occupy  an  upper  area  of  the 
640  KB  of  conventional  memory  above  MS-DOS  and  any  device  drivers 
and  RAM-resident  programs  that  may  be  loaded.  In  this  mode,  Windows 
can  take  advantage  of  any  expanded  memory  under  the  LIM  EMS  4.0.  This 
configuration  requires  an  EMS  memory  board  and  an  EMS  4.0  device 
driver. 

■  On  a  machine  based  around  the  Intel  286  processor  with  at  least  1  MB  of 
memory  (or  a  386  processor  with  less  than  2  MB  of  memory),  Windows  3.0 
runs  in  “standard  mode.”  This  is  286-compatible  protected  mode.  Win¬ 
dows  can  use  up  to  1 6  MB  of  conventional  memory  and  extended  memory. 
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■  On  a  machine  based  around  the  Intel  386  processor  with  at  least  2  MB  of 
memory,  Windows  3.0  runs  in  “386  enhanced  mode.”  This  is  essentially 
standard  mode  with  two  additional  features:  Windows  uses  the  paging 
registers  of  the  386  processor  to  implement  virtual  memory,  and  it  uses 
the  Virtual-86  mode  of  the  386  processor  to  support  multiple  virtual  MS- 
DOS  sessions. 

Many  developers  working  with  Windows  3.0 — particularly  those  writing  larger  pro¬ 
grams  that  could  not  run  well  on  anything  less  than  a  286  machine  with  1  MB  of  memory — 
decided  to  give  up  on  real  mode.  (As  you’ll  see,  abandoning  real  mode  simplifies  the  ways 
in  which  Windows  programs  use  memory.) 

With  Windows  3.1,  the  developers  of  Windows  have  also  decided  to  abandon  real 
mode.  Windows  3-1  runs  only  in  standard  mode  or  386  enhanced  mode.  If  you’re  going  to 
be  taking  advantage  of  Windows  3.1  features,  you  can  forget  about  real  mode  also,  and 
you’ll  probably  want  to  make  that  decision  regardless. 

Let’s  begin  by  reviewing  memory  handling  under  the  family  of  Intel  microprocessors, 
starting  back  in  the  old  days. 

MICROPROCESSORS  AND  MEMORY 

Before  MS-DOS  and  the  IBM  personal  computer  ever  existed,  there  existed  an  operating 
system  called  CP/M  (Control  Program  for  Microprocessors),  which  ran  on  personal  com¬ 
puters  built  around  the  Intel  8080  microprocessor  and,  later,  the  Zilog  Z-80,  which  imple¬ 
mented  a  superset  of  the  8080  instruction  set. 

The  8080  was  an  8-bit  microprocessor.  The  registers  used  for  storing  data  inside  the 
microprocessor  were  8  bits  in  length,  which  meant  that  arithmetic  and  logical  operations 
within  the  microprocessor  used  8-bit  quantities.  Thus,  adding  two  l6-bit  numbers  required 
two  additions  in  the  microprocessor.  The  8080  also  accessed  memory  8  bits  at  a  time.  To 
access  memory,  the  8080  could  combine  two  8-bit  registers  into  a  16-bit  address.  Thus,  the 
8080  address  space  was  65,536  bytes  (2  to  the  16th  power). 

The  Intel  8088 — the  microprocessor  IBM  decided  to  use  in  the  first  IBM  PCs  in 
1981 — and  the  Intel  8086  are  16-bit  microprocessors.  The  internal  registers  are  16  bits  in 
length,  which  means  that  arithmetic  and  logical  operations  could  be  performed  on  16-bit 
quantities.  This  improved  performance,  of  course. 

It  might  have  been  reasonable  to  expect  that  the  8088  could  combine  two  16-bit 
registers  into  a  32-bit  address  to  access  4  gigabytes  (GB)  of  memory  (2  to  the  32nd  power), 
but  this  was  not  the  case.  Partly  to  achieve  some  backward  compatibility  with  the  8080, 
partly  to  simplify  chip  construction,  and  partly  because  4  GB  of  memory  seemed  an  incon¬ 
ceivable  amount  at  the  time,  a  unique  form  of  segmented  memory  was  devised. 
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The  8088  has  four  special  internal  registers  called  “segment  registers.”  These  are 
called  the  CS  (code  segment),  DS  (data  segment),  SS  (stack  segment),  and  ES  (extra  seg¬ 
ment)  registers.  To  form  a  complete  address,  the  8088  shifts  the  contents  of  a  segment 
register  by  4  bits  and  adds  it  to  an  offset  address: 

Segment:  ssssssssssssssssOOOO 

+  Offset:  OOOOoooooooooooooooo 

=  Address:  aaaaaaaaaaaaaaaaaaaa 

This  creates  a  20-bit  address  that  can  access  up  to  1  MB  of  memory  (2  to  the  20th  power). 

When  it  designed  the  original  IBM  PC,  IBM  apportioned  this  1  MB  address  space  as 
follows:  The  highest  64  KB  of  memory  was  reserved  for  the  ROM  BIOS,  the  next  192  KB 
below  that  was  reserved  for  ROM  expansion,  and  the  next  128  KB  below  that  was  reserved 
for  the  memory  space  required  by  video  display  adapters,  for  a  total  of  384  KB.  Of  the  total 
1024-KB  memory  space,  that  leaves  the  famous  (and  infamous)  640  KB  of  read-write 
memory  we’ve  been  living  with  ever  since. 

The  lowest  area  of  this  640  KB  is  required  to  maintain  read-write  data  used  by  the 
ROM  BIOS.  MS-DOS  loads  above  that  area  and  then  loads  device  drivers  above  itself.  The 
rest  of  the  640  KB  can  be  occupied  by  programs  running  under  MS-DOS. 

Near  Addresses  and  Far  Addresses 

A  program  running  under  the  8088  requires  two  16-bit  values  (a  segment  address  and  an 
offset  address)  to  form  a  20-bit  full  address  to  access  physical  memory.  These  values  need 
not  be  unique.  For  example,  if  the  segment  address  is  0x0010  and  the  offset  address  is 
0x4000,  the  physical  address  is  0x4100.  This  same  physical  address  can  also  be  formed  by  a 
segment  address  of  0x400  and  an  offset  address  of  0x100. 

Software  for  the  8086  family  runs  most  efficiently  when  the  segment  addresses  are 
held  constant  and  all  addressing  is  done  by  varying  the  offset  addresses.  The  offset  ad¬ 
dresses  stored  in  the  microprocessor  include  the  IP  (instruction  pointer),  which  accesses 
code  in  combination  with  the  CS  register;  the  SP  (stack  pointer)  and  BP  (base  pointer), 
which  access  the  stack  in  combination  with  the  SS  register;  and  the  BX  (base),  SI  (source 
index),  and  DI  (destination  index)  registers,  which  access  data,  most  often  in  combination 
with  the  DS  or  ES  register. 

When  a  segment  address  is  held  constant,  an  offset  address  can  vary  from  0x0000 
through  OxFFFF  and  access  64  KB  of  memory.  A  block  of  memory  that  is  based  on  a  par¬ 
ticular  segment  address  is  called  (appropriately  enough)  a  “segment.”  People  used  to  think 
of  segments  as  64-KB  blocks  of  memory,  but  this  definition  is  becoming  less  common. 
Now  we  say  that  segments  can  be  any  size  up  to  64  KB. 

An  address  that  uses  only  the  offset  address  with  an  implied  segment  address  is 
called  a  “near  pointer”  or  sometimes  a  “short  pointer.”  An  address  that  uses  both  the 
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segment  and  offset  addresses  is  called  a  “far  pointer”  or  a  “long  pointer.”  Far  pointers  can 
be  stored  in  memory  as  32-bit  quantities,  even  though  they  produce  only  a  20-bit  physical 
address. 

The  easiest  way  for  a  small  program  to  use  the  8088  is  to  set  all  the  segment  registers 
to  the  same  value  and  leave  them  that  way.  The  program  can  then  simply  use  the  16-bit  off¬ 
set  registers  to  access  memory.  This  is  the  foundation  of  the  .COM  programs  that  formerly 
were  so  prevalent  under  MS-DOS  and  that  are  structurally  similar  to  CP/M  programs.  The 
only  problem  is  that  such  programs  are  limited  to  a  total  of  64  KB  of  code  and  data.  Going 
beyond  the  64-KB  segment  requires  loading  a  segment  register  with  a  different  value. 

As  MS-DOS  programs  grew  beyond  64  KB,  the  .EXE  file  format  of  executables 
became  more  popular.  This  format  allowed  separate  multiple  segments  for  code  and  data. 
Often  one  of  the  data  segments  is  known  as  the  “default”  data  segment  because  it  contains 
all  of  the  program’s  initialized  data  and  is  also  used  for  the  stack.  In  the  simplest  case,  one 
segment  can  store  the  code  and  one  segment  can  store  data.  Programs  requiring  more  than 
64  KB  of  code  or  data  deal  with  both  near  and  far  pointers. 

Protected  Mode 

With  the  introduction  of  the  Intel  286  microprocessor,  things  changed.  The  286  can  run  in 
two  modes,  called  “real  mode”  and  “protected  mode.”  Real  mode  is  essentially  compatible 
with  the  8088.  Protected  mode  expands  the  physical  address  space  to  16  MB  (2  to  the  24th 
power)  and  offers  better  memory  management. 

Protected  mode  has  the  same  segment  registers  (CS,  DS,  ES,  and  SS)  as  real  mode,  but 
the  segment  address  is  known  as  a  “selector.”  Protected  mode  requires  a  block  of  memory 
(usually  set  up  by  a  protected  mode  operating  system)  known  as  a  “descriptor  table.”  The 
descriptor  table  can  contain  up  to  8,192  8-byte  entries.  The  upper  13  bits  of  the  selector 
references  one  of  these  entries.  The  entry  in  the  descriptor  table  contains  a  24-bit  “base 
address”  that  is  then  added  to  the  offset  address  to  form  a  24-bit  physical  address: 

Selector:  ssssssssssssssss 

Descriptor 
Table 

Base:  bbbbbbbbbbbbbbbbbbbbbbbb 

+  Offset:  OOOOOOOOoooooooooooooooo 

=  Address:  aaaaaaaaaaaaaaaaaaaaaaaa 

The  24-bit  address  allows  accessing  16  MB  of  physical  memory.  The  descriptor  table  entry 
also  includes  such  information  as  the  size  of  the  segment,  whether  it’s  code  or  data,  and  its 
privilege  level.  This  information  is  used  for  implementing  protection. 
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As  I  mentioned  at  the  outset  of  this  chapter,  proper  memory  management  requires 
memory  movement.  If  a  program  is  using  near  pointers  to  access  a  single  segment  and  the 
segment  must  be  moved,  then  it  doesn’t  matter  where  the  segment  is  located  in  physical 
memory.  All  that  needs  to  be  changed  is  the  segment  register. 

In  protected  mode,  this  thinking  goes  one  step  further.  If  a  program  is  using  far 
pointers  to  access  memory,  then  segments  can  be  moved — and  all  that  needs  to  be 
changed  is  the  base  address  in  the  descriptor  table.  This  can  be  handled  by  the  operating 
system  transparent  to  the  application. 

Only  the  upper  13  bits  of  the  selector  are  used  for  referencing  the  descriptor  table. 
The  lowest  2  bits  of  the  selector  are  used  in  some  operating  systems  for  implementing  priv¬ 
ilege  levels.  They  are  not  used  in  Windows  for  this  purpose.  Instead,  the  bits  are  set  to  10 
for  a  moveable  memory  segment  and  to  11  for  a  fixed  (unmoveable)  memory  segment. 
(Moveable  and  fixed  segments  are  described  in  greater  detail  later  in  this  chapter.) 

The  third  less-significant  bit  of  the  selector  indicates  which  descriptor  table  to  use.  In 
protected  mode,  there  are  two  types  of  descriptor  tables:  a  global  descriptor  table  (GDT) 
and  a  local  descriptor  table  (LDT).  Only  one  GDT  can  be  used,  but  multiple  LDTs  can  be 
used.  However,  only  one  LDT  is  active  at  any  time.  The  third  less-significant  bit  of  the 
selector  is  set  to  0  to  indicate  the  GDT  or  to  1  to  indicate  the  LDT. 

Generally,  in  a  multitasking  operating  system,  the  GDT  is  used  to  manage  operating 
system  memory.  Each  process  gets  its  own  LDT  for  its  own  memory.  In  this  way,  processes 
are  protected  from  interfering  with  each  other.  However,  Windows  uses  a  single  LDT  that  is 
shared  among  the  operating  system  and  all  Windows  processes.  Every  selector  used  in 
Windows  has  the  third  less-significant  bit  set  to  1. 

With  protected  mode,  several  rules  are  imposed  on  you  (the  programmer): 

■  Do  not  perform  segment  arithmetic.  The  segment  address  is  not  a  real 
memory  address. 

■  Do  not  assume  that  a  segment:offset  address  of  1100:0020  accesses  the 
same  memory  as  1000:1020. 

■  Do  not  load  far  pointers  with  invalid  addresses.  (Setting  a  far  pointer  to 
NULL  is  allowed.) 

■  Do  not  attempt  to  address  a  segment  beyond  its  allocated  size. 

■  Do  not  increment  an  offset  address  past  OxFFFF. 

■  Do  not  attempt  to  write  into  a  code  segment  (that  is,  create  self-modifying 
code). 

As  you’ve  probably  figured  out  by  now,  segments  are  central  to  Windows’  memory 
organization.  The  entire  memory  space  controlled  by  Windows  is  divided  into  segments  of 
various  lengths.  Some  of  these  segments  contain  code,  and  others  contain  data. 
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MEMORY  ORGANIZATION  IN  WINDOWS 

The  entire  memory  area  that  Windows  controls  is  called  “global  memory”  or  the  “global 
heap.”  This  area  begins  at  the  location  where  MS-DOS  first  loads  Windows  into  memory 
and  ends  at  the  top  of  available  memory  which  most  often  is  the  top  of  physical  memory. 
(Note:  In  C  programming,  the  term  global  usually  refers  to  variables  or  functions  in  one 
source  code  file  that  can  be  referenced  from  functions  in  another  source  code  file  of  the 
same  program.  In  literature  discussing  protected  mode,  the  term  global  refers  to  memory 
available  in  the  global  descriptor  table.  In  this  discussion  of  Windows’  memory  organiza¬ 
tion,  the  term  global  instead  means  “everything.”)  Every  block  of  memory  allocated  from 
the  global  heap  is  a  segment.  Global  memory  not  currently  allocated  is  called,  appropri¬ 
ately  enough,  free  memory. 

A  Windows  program  can  have  one  or  more  code  segments  and  one  or  more  data  seg¬ 
ments.  (The  example  programs  shown  in  this  book  have  only  one  of  each.)  When  Win¬ 
dows  loads  a  program  into  memory,  it  allocates  at  least  one  segment  from  the  global  heap 
for  code  and  one  segment  for  data.  When  the  program  begins  to  execute,  the  microproces¬ 
sor’s  CS  register  is  set  to  the  segment  address  of  the  code  segment  that  contains  the  entry 
point  of  the  program.  The  DS  and  SS  registers  are  set  to  the  segment  address  of  the  pro¬ 
gram’s  automatic  (or  default)  data  segment,  which  is  the  data  segment  that  contains  the 
stack.  (The  combination  of  the  data  and  the  stack  into  one  segment  referenced  by  both  DS 
and  SS  is  normal  for  C  compilers.  DS  is  used  to  reference  data  declared  as  static;  SS  is  used 
to  reference  data  on  the  stack,  which  includes  local  nonstatic  data  and  arguments  passed  to 
functions.  This  approach  allows  near  pointers  to  be  used  for  function  parameters.  The 
function  doesn’t  have  to  know  whether  it’s  dealing  with  static  data  or  stack  data.  Problems 
related  to  unidentical  DS  and  SS  segment  registers  are  discussed  in  Chapter  19,  “Dynamic 
Link  Libraries.”) 

When  loading  a  program,  Windows  also  allocates  two  other  segments  from  the 
global  heap  for  program  overhead.  One  of  these  segments  contains  the  header  portion  of 
the  program’s  .EXE  file.  This  segment  is  used  for  all  instances  of  a  program,  so  it  is  allo¬ 
cated  only  for  the  first  instance.  The  other  segment  contains  information  unique  to  each  in¬ 
stance,  such  as  the  program’s  command-line  string  and  the  program’s  current 
subdirectory.  When  a  program  loads  resources  (such  as  icons,  cursors,  or  menu  templates) 
into  memory,  each  resource  gets  its  own  segment  in  the  global  heap.  A  program  may  itself 
also  allocate  some  memory  from  the  global  heap. 

If  a  program  has  only  one  code  segment,  any  calls  it  makes  to  functions  within  the 
program  are  compiled  as  near  calls.  The  CS  code  segment  register  remains  the  same.  How¬ 
ever,  when  a  program  calls  a  Windows  function,  the  Windows  function  is  in  a  different 
code  segment.  This  situation  requires  that  the  compiler  generate  a  far  call,  which  is  the 
reason  that  all  Windows  functions  (and  all  functions  within  your  program  that  are  called 
by  Windows)  must  be  declared  as  far. 


277 


SECTION  III:  USING  RESOURCES 


A  Windows  program  that  has  one  data  segment  can  use  near  pointers  to  access 
memory  within  that  data  segment.  However,  when  a  Windows  program  passes  a  pointer  to 
a  Windows  function,  the  pointer  must  be  a  far  (or  long)  pointer;  otherwise,  the  code  that 
contains  the  Windows  function  would  use  its  own  data  segment.  Far  pointers  are  required 
so  that  the  Windows  function  can  access  the  data  within  your  program’s  data  segment. 

Fixed  and  Moveable  Segments 

Every  segment  in  Windows’  total  memory  space  is  marked  with  certain  attributes  that  tell 
Windows  how  to  manage  the  segment.  First  and  foremost,  segments  are  marked  as  either 
“fixed”  or  “moveable.”  Windows  can  move  moveable  segments  in  memory  if  necessary  to 
make  room  for  other  memory  allocations.  A  fixed  segment  always  resides  at  the  same 
physical  memory  location  where  it  was  first  allocated. 

In  real  mode,  when  Windows  moves  a  moveable  segment  in  memory,  all  existing 
near  pointers  to  memory  within  that  segment  continue  to  be  valid  because  near  pointers 
reference  an  offset  from  the  beginning  of  a  segment.  However,  far  pointers  become  in¬ 
valid.  In  protected  mode,  far  pointers  as  well  as  near  pointers  continue  to  be  valid  because 
Windows  simply  alters  the  descriptor-table  entry.  The  selector  is  the  same  regardless  of 
where  the  memory  block  is  located  in  physical  memory. 

Most  segments — including  the  segments  allocated  for  your  program’s  code  and 
data — are  normally  moveable  in  either  real  or  protected  mode. 

A  fixed  segment  cannot  be  moved  in  memory.  Segments  must  be  marked  as  fixed  if 
Windows  is  incapable  of  modifying  an  existing  far  pointer  to  the  segment.  In  protected 
mode,  fixed  segments  have  become  much  less  necessary  than  in  real  mode,  but  some  ex¬ 
ceptions  still  exist.  In  particular,  dynamic  link  libraries  that  handle  hardware  interrupts 
have  fixed  code  and  data  segments.  This  is  necessary  when  working  with  some  functions 
(for  example,  timeSetEvent )  included  in  the  multimedia  extensions  to  Windows. 

Here’s  one  way  Windows  deals  with  moveable  segments.  You’ve  seen  how  Windows 
and  your  programs  use  numbers  called  “handles.”  In  many  cases,  the  handles  are  really 
near  pointers.  In  real  mode,  Windows  maintains  a  segment  called  BURGERMASTER 
(named  after  a  favorite  restaurant  of  the  early  Windows  developers)  that  contains  a  master 
handle-to -memory  table.  The  handle  points  to  a  small  area  of  memory  within  BURGER- 
MASTER  that  contains  the  segment  address  of  the  item  that  the  handle  references.  When 
Windows  moves  the  segment  that  contains  the  item,  it  can  adjust  the  address  in  BURGER- 
MASTER  without  invalidating  the  handle.  BURGERMASTER  is  itself  a  moveable  segment. 

In  real  mode,  Windows  does  not  directly  make  calls  to  window  procedures,  dialog 
procedures,  or  call-back  functions.  Instead,  Windows  builds  a  small  piece  of  code  called  a 
“thunk,”  which  assigns  the  segment  address  of  the  default  data  segment  before  entering 
the  program.  (This  is  the  purpose  of  the  MakeProcInstance  function.)  When  Windows 
moves  your  default  data  segment,  all  it  needs  to  do  is  change  the  thunk. 
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You  should  try  very  hard  to  ensure  that  the  code  and  data  segments  of  your  Windows 
programs  (as  well  as  any  additional  segments  your  programs  allocate)  are  moveable 
segments.  Fixed  segments  stand  like  brick  walls  in  memory  space  and  clog  up  Windows’ 
memory  management.  Users  quickly  learn  which  programs  seem  to  use  little  memory 
(because  they  use  moveable  segments)  and  which  programs  seem  to  use  a  lot  of  memory 
(because  they  use  fixed  segments).  Users  have  a  name  for  a  program  that  uses  a  lot  of 
memory:  pig.  They  can  be  heard  to  say,  “This  program  is  a  real  pig.”  Your  goal  should  be  to 
write  programs  that  are  not  pigs. 

Discardable  Memory 

Moveable  segments  can  also  be  marked  as  discardable.  This  means  that  when  Windows 
needs  additional  memory  space,  it  can  free  up  the  area  occupied  by  the  segment.  Windows 
uses  a  “least  recently  used”  (LRU)  algorithm  to  determine  which  segments  to  discard  when 
attempting  to  free  up  memory. 

Discardable  segments  are  almost  always  read-only  segments  that  do  not  change  after 
they  are  loaded.  Code  segments  of  Windows  programs  are  discardable  because  (in  most 
cases)  programs  do  not  modify  their  code  segments.  When  Windows  discards  a  code  seg¬ 
ment,  it  can  later  reload  the  code  segment  by  accessing  the  .EXE  file.  Most  of  Windows’ 
own  code  in  the  USER  and  GDI  modules  and  in  various  driver  libraries  is  also  discardable. 
(The  Kernel  module  is  an  exception  because  this  is  the  module  responsible  for  Windows’ 
memory  management.)  Resources  (such  as  dialog  box  templates,  cursors,  and  icons)  also 
are  often  marked  as  discardable.  Again,  Windows  can  simply  reload  the  resource  into 
memory  by  accessing  the  .EXE  file  that  contains  the  resource. 

Sometimes  you’ll  see  that  a  disk  is  being  accessed  when  you  move  the  mouse  from  the 
client  area  of  one  program  to  the  client  area  of  another.  Why  is  this?  Windows  has  to  send 
mouse  movement  messages  to  the  second  application.  If  the  program’s  code  to  process  this 
message  is  not  currently  in  memory,  Windows  must  reload  it  from  the  disk  file.  If  you  have 
several  large  Windows  programs  loaded  simultaneously  and  not  much  memory,  you  will 
probably  witness  some  “thrashing”  (an  inordinate  amount  of  disk  activity)  as  you  move  from 
program  to  program — because  Windows  is  reloading  previously  discarded  segments. 

Discardable  segments  must  also  be  moveable  segments  because  discardable  seg¬ 
ments  can  be  reloaded  in  a  different  area  of  memory  than  the  area  they  occupied  earlier. 
However,  moveable  segments  are  not  always  discardable  segments.  This  is  usually  the  case 
with  data  segments.  Windows  cannot  discard  a  program’s  automatic  data  segment  because 
the  segment  always  contains  read-write  data  and  the  stack. 

The  Global  Memory  Layout 

As  I  noted  before,  global  memory  ranges  from  the  spot  where  MS-DOS  first  loads  Windows 
to  the  top  of  available  memory.  At  the  bottom  of  global  memory  (the  area  with  the  lowest 
memory  address),  Windows  allocates  fixed  segments.  Fixed  segments  are  allocated  from 
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the  bottom  up.  At  the  top  of  global  memory,  Windows  allocates  discardable  code  segments. 
(Remember  that  discardable  segments  are  also  moveable  segments.)  Discardable  code 
segments  are  allocated  from  the  top  down. 

Between  fixed  segments  and  discardable  code  segments,  Windows  allocates  move- 
able  segments  and  nondiscardable  data  segments.  The  largest  block  of  free  memory  is  usu¬ 
ally  located  below  the  discardable  code  segments.  The  memory  layout  looks  something 
like  that  shown  in  Figure  7-1;  arrows  indicate  the  direction  in  which  the  areas  expand. 


Top  of  memory 


Bottom  of  memory 


Figure  7-1 .  The  organization  of  global  memory. 

Here  is  how  Windows  allocates  a  new  memory  segment.  When  Windows  needs  to 
allocate  a  fixed  segment,  it  starts  searching  from  the  bottom  up  for  a  sufficiently  large  free 
block  below  the  area  of  moveable  segments.  If  it  can’t  find  one,  it  starts  moving  moveable 
segments  up  in  memory  to  make  room.  If  that  doesn’t  work,  Windows  begins  discarding 
discardable  segments,  based  on  an  LRU  (least  recently  used)  algorithm,  again  moving 
moveable  segments.  To  allocate  moveable  but  nondiscardable  segments,  Windows 
searches  the  free  memory  area  below  the  discardable  segments.  If  it  doesn’t  find  enough 
room,  Windows  moves  other  moveable  segments  down  in  memory  and  eventually  starts 
discarding  discardable  segments. 

When  running  in  386  enhanced  mode,  Windows  implements  a  virtual  memory 
scheme  based  on  386  page  registers.  When  memory  is  needed  and  physical  memory  is  not 
available,  Windows  can  swap  pages  out  to  disk  and  later  reload  them  when  necessary.  This 
virtual  memory  process  has  priority  over  the  discarding  of  memory  segments. 

Within  the  area  of  discardable  memory,  Windows  maintains  a  space  large  enough  to 
accommodate  the  largest  code  segment  of  every  currently  running  program.  Windows 
never  runs  out  of  memory  space  when  reloading  code  segments.  However,  Windows  can 
run  out  of  memory  space  when  a  program  attempts  to  allocate  global  memory  or  to  load  a 
resource.  Sometimes  it  can  be  a  little  tricky  to  deal  with  this  problem — you  may  need  a 
text  string  or  icon  not  currently  in  memory  to  display  an  error  message.  If  your  program 
needs  to  report  that  it  is  low  on  memory,  you  can  use  a  message  box.  Windows  keeps  in 
memory  all  the  code  necessary  to  create  a  message  box.  You’ll  want  to  use  the 
MB-SYSTEMMODAL  flag  to  prevent  the  user  from  switching  to  another  application. 
IDI_STOPICON  (which  is  supposed  to  accompany  messages  indicating  severe  problems) 
is  also  always  in  memory.  The  text  message  in  the  message  box  should  either  be  in  your 
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default  data  segment  or  be  a  string  resource  that  has  previously  been  copied  into  your  data 
segment. 

Local  Memory 

Every  Windows  program  has  at  least  one  data  segment  called  the  “default,”  or  “automatic,” 
data  segment.  A  program’s  DS  and  SS  segment  registers  both  point  to  this  segment.  In  con¬ 
trast  to  the  “global  memory”  that  Windows  manages,  this  automatic  data  segment  is  called 
your  program’s  “local  memory.”  Within  Windows’  global  memory  organization,  your  pro¬ 
gram’s  automatic  data  segment  is  most  often  a  moveable  but  nondiscardable  segment.  The 
segment  is  called  DGROUP. 

In  both  regular  MS-DOS  C  programs  and  Windows  programs,  the  memory  within 
DGROUP  is  organized  into  four  areas,  as  shown  in  Figure  7-2.  These  four  areas  are  de¬ 
scribed  below: 

■  Initialized  static  data — This  area  contains  initialized  variables  defined 
outside  of  functions,  initialized  static  variables  within  functions,  and 
explicit  strings  and  floating-point  numbers. 

■  Uninitialized  static  data — This  area  has  uninitialized  variables  that  are 
defined  outside  of  functions  and  uninitialized  variables  defined  as  static 
within  functions.  In  accordance  with  C  standards,  all  uninitialized  static 
variables  are  initialized  to  0  when  the  data  segment  is  created  in  memory. 

■  Stack — This  area  is  used  for  “automatic”  data  items  defined  within 
functions  (variables  not  defined  as  static),  for  data  passed  to  functions, 
and  for  return  addresses  during  function  calls. 

■  Local  heap — This  is  free  memory  available  for  dynamic  allocation  by  the 
program. 

Top  of  DGROUP 


Bottom  of  DGROUP 


Figure  7-2.  The  organization  of  memory  in  DGROUP. 

The  module  definition  (.DEF)  file  specifies  your  program’s  stack  size  and  local  heap  size: 

HEAPSIZE  1024 
STACKSIZE  8192 

In  a  regular  C  program,  you  can  allocate  memory  from  the  local  heap  using  the 
malloc  and  calloc  functions.  In  Windows  programs,  you  can  also  allocate  memory  from 
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the  local  heap  using  these  functions,  but  you  may  want  to  use  the  Windows  memory  alloca¬ 
tion  functions  rather  than  the  C  functions.  When  you  use  Windows  functions  to  allocate 
local  memory  you  can  allocate  moveable  and  discardable  blocks  of  memory.  Windows 
organizes  the  local  heap  very  much  like  global  memory,  as  shown  in  Figure  7-3.  Although 
the  stack  is  fixed  in  size,  Windows  can  dynamically  expand  the  local  heap  if  you  attempt  to 
allocate  more  local  memory  than  is  specified  in  your  module  definition  file.  Windows  can 
even  move  your  data  segment  if  that  is  necessary  to  expand  the  local  heap. 

Top  of  local  heap 


Bottom  of  local  heap 


Figure  7-3.  The  organization  of  the  local  heap. 
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CODE  AND  DATA  SEGMENTS 

All  the  Windows  programs  shown  so  far  have  one  code  segment  and  one  data  segment. 
Windows  programs  can  also  have  multiple  code  and  data  segments.  For  larger  programs, 
using  multiple  code  segments  is  highly  recommended  because  it  helps  relieve  memory 
congestion  in  Windows.  Using  multiple  data  segments,  on  the  other  hand,  can  be  a  prob¬ 
lem.  Let’s  take  a  look  at  this  subject. 

Small,  Medium,  Compact,  Large,  and  Huge  Memory  Models 

When  we  speak  about  a  program  having  one  code  or  data  segment  or  multiple  code  or  data 
segments,  we’re  referring  to  “memory  models.”  The  Microsoft  and  Borland  C  compilers 
support  five  memory  models  that  you  can  use  for  Windows  programs: 
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Command-line  switches  of  the  compiler  determine  the  memory  model  you  use.  The 
small-memory  model  is  the  default,  but  programs  that  have  more  than  64  KB  of  code  must 
contain  two  or  more  code  segments,  and  programs  that  have  more  than  64  KB  of  data  must 
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contain  two  or  more  data  segments.  In  medium-model  and  large-model  programs,  all  func¬ 
tions  (unless  explicitly  declared  as  near)  are  far,  and  the  compiler  generates  far  calls  for 
them.  In  compact-model  and  large-model  programs,  all  data  references  use  far  pointers. 

The  small,  compact,  medium,  and  large  models  each  have  their  own  C  libraries.  The 
medium-model  and  large-model  libraries  contain  functions  that  assume  they  have  been 
called  from  another  segment.  The  functions  in  the  compact-model  and  large-model  librar¬ 
ies  always  assume  they  have  been  passed  long  pointers  to  data.  The  huge  model  is  essen¬ 
tially  the  same  as  the  large  model  except  that  individual  data  items  may  be  greater  than 
64  KB.  The  huge  model  has  limited  library  support. 

Most  small  Windows  programs  are  compiled  as  small  model,  with  one  code  segment 
and  one  data  segment.  Strictly  speaking,  however,  Windows  programs  are  really  “mixed- 
model”  programs  because  they  extensively  call  far  functions.  Windows  programs  make  far 
calls  to  Windows  functions,  and  Windows  makes  far  calls  to  functions  within  a  program, 
such  as  window  procedures  or  call-back  functions.  All  data  pointers  passed  between  a 
program  and  Windows  (with  one  oddball  exception — the  GetlnstanceData  function)  are 
far  pointers. 

Windows  programs  can  also  be  compiled  as  medium-model  programs.  You  can  try 
this  out  on  any  of  the  programs  shown  so  far,  but  you’ll  need  to  make  two  changes  to  the 
make  file: 

■  Add  the  -AM  switch  (for  Microsoft  C/C++  7.0)  or  the  -mm  switch  (for 
Borland  C++  3.1)  to  the  compile  step.  This  compiles  for  the  medium 
model. 

■  For  Microsoft  C/C++  7.0,  change  SLIBEW  to  MLIBEW  in  the  link  step.  This 
is  the  library  that  contains  the  Windows-specific  C  run  time  library 
functions.  For  Borland  C++  3.1,  change  COWS,  CWS,  and  MATHWS  to 
COWM,  WWM,  and  MATHWM. 

Delete  the  .OBJ  file  and  run  NMAKE  or  MAKE.  You’ll  find  that  the  .EXE  file  is  some¬ 
what  larger  than  before  because  all  the  functions  within  your  program — not  only  the 
window  procedure  and  call-back  functions — now  require  far  calls. 

Multiple  Code  Segments 

The  medium  model  doesn’t  make  sense  for  a  small  program,  and  it  comes  into  play  only 
when  you  have  more  than  one  source  code  module.  But  then  it  begins  to  make  a  lot  of 
sense.  In  the  medium  model,  each  source  code  module  can  become  a  different  code  seg¬ 
ment.  Each  of  these  code  segments  can  be  moveable  and  discardable.  The  amount  of  space 
required  to  fit  your  code  into  memory  is  the  size  of  the  largest  code  segment. 

For  instance,  the  approximately  220  KB  of  code  in  Windows  WRITE  is  distributed 
among  83  separate  moveable  and  discardable  code  segments.  The  largest  code  segment  in 


283 


SECTION  III:  USING  RESOURCES 


WRITE  is  about  9  KB.  Thus,  when  memory  is  limited,  WRITE  can  continue  to  run  with 
only  a  9-KB  code  space.  As  program  logic  within  WRITE  moves  from  segment  to  segment, 
the  code  segment  currently  in  memory  can  be  discarded  and  a  new  one  loaded  in.  Perfor¬ 
mance  would  be  crippled,  of  course,  but  it  would  work. 

If  you  like,  you  can  think  of  the  medium  model  as  a  simplified  overlay  manager:  You 
split  your  program  into  multiple  source  code  modules  and  compile  for  the  medium  model, 
and  Windows  does  the  rest.  In  order  to  work  efficiently,  the  medium-model  approach  re¬ 
quires  some  planning.  The  functions  in  each  of  your  source  code  modules  should  be 
organized  in  functional  groups.  When  your  program  is  dealing  with  such  routine  matters 
as  processing  mouse  messages,  for  example,  it  should  not  have  to  load  several  code  seg¬ 
ments  to  get  from  the  top  of  the  window  procedure  to  the  bottom. 

Although  using  the  medium  model  is  certainly  the  easiest  approach  to  take  with  a 
large  program,  it  is  not  the  most  efficient.  When  you  compile  a  program  for  Windows,  the 
compiler  adds  some  extra  prolog  code  to  all  far  functions.  Only  those  functions  actually 
called  by  Windows  (such  as  window  procedures  or  call-back  functions)  need  this  prolog 
code,  however.  When  all  the  functions  in  your  program  are  far  functions  (as  they  are  in  the 
medium  model),  this  extra  code  can  add  up  to  a  significant  waste  of  space. 

There  are  several  solutions  to  this  problem.  The  first  is  fairly  simple.  When  compiling 
a  module  that  does  not  include  any  functions  that  are  called  from  Windows  (such  as  win¬ 
dow  procedures,  dialog  procedures,  or  call-back  functions),  compile  with  the  -GW  switch 
rather  than  the  -Gw  switch.  This  reduces  the  prolog  code  on  far  functions. 

Another  approach  to  reduce  wasted  space  in  a  medium-model  program  is  to  define 
as  near  functions  all  functions  used  only  within  a  module.  Yet  another  solution  is  to 
use  a  mixed  model  with  a  small  model  as  a  base.  Let’s  assume  you  have  five  source  code 
modules: 

■  Module  1  contains  WinMain,  the  message  loop,  your  window  procedure, 
and  most  message  processing. 

■  Module  2  contains  one  function  that  has  all  the  initialization  code.  This 
function  is  called  by  WinMain  from  Module  1  before  entering  the  mes¬ 
sage  loop. 

■  Module  3  contains  one  function  called  from  your  window  procedure  and 
several  other  functions  called  only  within  this  module. 

■  Module  4  also  contains  a  function  called  from  your  window  procedure 
and  several  other  functions  called  only  within  this  module.  This  module 
also  calls  a  function  in  Module  5. 

■  Module  3  contains  a  function  called  from  Module  4  and  several  other 
functions  called  only  within  this  module. 
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You  can  organize  this  program  into  four  segments,  with  Modules  4  and  5  in  a  single 
segment.  Within  each  module,  you  explicitly  define  as  far  any  function  called  from  outside 
the  segment.  This  involves  one  function  each  in  Modules  2,  3,  and  4.  In  the  modules  that  call 
these  functions,  the  functions  must  be  declared  as  far  using  the  function  name  prefaced 
by  FAR  near  the  top  of  the  program. 

You  compile  each  module  for  the  small  model  except  that  you  assign  one  code  seg¬ 
ment  name  to  Module  2,  another  to  Module  3,  and  yet  another  to  Modules  4  and  5.  These 
names  are  assigned  by  including  the  -NT  (“name  the  text  segment”)  switch  when  compiling 
under  the  Microsoft  compiler  or  the  -zC  switch  when  compiling  under  the  Borland  compiler. 
Each  module  with  the  same  code  segment  name  is  in  the  same  segment.  Now  you  have  far 
functions  only  where  you  need  them — for  functions  that  are  called  from  another  segment. 

As  you  can  see,  this  mixed-model  approach  is  more  of  a  headache  than  the  medium- 
model  approach.  It  requires  that  you  figure  out  which  functions  must  be  declared  far  and 
which  can  be  near.  It  also  has  an  additional  problem:  You  can  call  normal  C  library  routines 
from  only  one  segment — the  segment  that  gets  the  default  segment  name  -TEXT  when 
you  compile  without  the  -NT  switch. 

What  About  the  Compact  and  Large  Models? 

Windows  programmers  who  require  more  than  64  KB  of  data  in  their  programs  might  be 
feeling  a  little  nervous  at  this  point.  They  have  a  right  to  be  because  the  compact  and  large 
models  are  not  recommended  for  Windows  programs.  This  doesn’t  mean  they  can’t  be 
used,  however.  The  Windows  Software  Development  Kit  allows  you  to  install  compact- 
model  and  large-model  Windows  libraries,  so  obviously  these  models  are  legal.  However, 
compact-model  and  large-model  programs  are  subject  to  a  very  strict  penalty:  The  addi¬ 
tional  data  segments  must  be  fixed  in  memory.  They  cannot  be  flagged  as  moveable. 
In  addition,  only  one  instance  of  the  program  can  be  run  at  any  time. 

Why  this  restriction?  There  are  various  reasons.  Here’s  an  easy  example  that  illus¬ 
trates  one  of  them.  Suppose  that  somewhere  within  your  program  you  define  a  static 
pointer  that  looks  like  this: 

char  *  pointer  ; 

Because  you’re  compiling  for  a  compact  or  large  model,  this  is  a  far  pointer.  During 
your  program’s  execution,  you  assign  a  value  to  that  pointer.  If  the  pointer  references  a 
moveable  data  segment,  the  value  of  the  pointer  must  be  adjusted  when  Windows  moves 
the  data  segment  it  references.  But  the  compiler  and  linker  will  not  even  generate  a  reloca¬ 
tion  address  for  that  pointer  because  it’s  not  initialized. 

Program  developers  who  cry  “but  I  need  the  large  model”  should  consider  the  alter¬ 
natives  made  evident  by  existing  Windows  applications.  Take  a  look  at  some  large  Win¬ 
dows  programs  (such  as  Word  for  Windows)  and  you’ll  see  that  these  programs  use  many 
code  segments  but  only  one  data  segment.  If  these  programs  don’t  need  the  large  model, 
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then  you  probably  don’t  either.  If  your  program  needs  more  than  64  KB  of  data,  you  have 
alternatives  to  using  the  compact  or  large  model.  Here  they  are: 

■  If  your  program  uses  large  blocks  of  uninitialized  data,  do  not  define 
these  data  as  variables  within  the  program.  Instead,  use  the  Windows 
GlobalAlloc  function  (discussed  later  in  this  chapter)  to  allocate  a  block  of 
moveable  memory  outside  your  program. 

■  If  your  program  uses  large  blocks  of  initialized  read-only  data  (the  most 
obvious  example  is  “help”  text),  make  the  data  a  discardable  “user- 
defined  resource”  (discussed  in  Chapter  8)  to  be  loaded  from  the  disk 
only  when  necessary.  This  keeps  the  data  out  of  memory  when  not 
needed. 

■  If  your  program  uses  large  blocks  of  initialized  read-write  data,  store  the 
data  in  a  file,  or  put  the  initialized  data  in  a  discardable  “user-defined 
resource”  (discussed  in  Chapter  8)  and  transfer  the  data  to  a  global 
memory  block  allocated  with  GlobalAlloc. 

Avoiding  Movement  Problems 

We  have  been  creating  small  Windows  programs  for  several  chapters  now  and  have  not 
run  into  problems  when  Windows  has  moved  the  code  and  data  segments  in  memory. 
Here  are  some  general  rules  for  continuing  to  avoid  problems: 

■  Use  the  small  model  or  medium  model. 

■  Don’t  declare  any  variables  as  far.  For  instance,  don’t  do  something  like  this: 

int  far  array  [10] [1000]  ;  //  Bad!!!!! 

This  code  creates  a  second  data  segment  in  your  program.  Unless  you 
mark  this  segment  as  fixed,  Windows  does  not  properly  handle 
references  to  this  array,  and  only  one  instance  of  the  program  can  be  run 
at  any  time. 

■  Don’t  store  any  far  pointers  to  data  except  those  that  Windows  gives  you. 

The  IpszCmdLine  parameter  passed  to  WinMain  is  OK.  The  far  addresses 
returned  from  GlobalLock  (discussed  later  in  this  chapter)  and 
LockResource  (discussed  in  Chapter  8)  point  to  fixed  data  until  you 
specifically  unlock  the  data,  so  these  are  legitimate  also.  Some  window 
messages  (WM -CREATE,  for  instance)  have  IParam  values  that  are  far 
pointers.  Use  these  pointers  only  for  the  duration  of  the  message. 

■  When  you  call  Windows  functions,  you  must  often  pass  far  pointers  to 
data  that  are  within  your  data  segment.  But  don’t  declare  far  pointers  and 
assign  them  far  addresses  to  local  data  items  and  then  later  use  the  far 
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pointers  when  calling  Windows  functions.  Instead,  cast  the  near  pointers 
into  far  pointers  when  you  call  the  functions,  or  let  the  compiler  do  this 
casting  for  you. 

■  Don’t  store  or  use  any  far  pointers  to  code,  except  for  pointers  to  functions 
that  are  specifically  declared  as  far  or  that  are  far  pointers  returned  from 
MakeProcInstance.  (Pointers  to  functions  in  medium-model  programs 
are  also  OK.) 

■  When  you  need  to  give  Windows  a  far  pointer  to  a  function  for  a  call-back 
function  (as  discussed  in  Chapter  5),  a  window  subclassing  function  (as 
discussed  in  Chapter  6),  or  a  dialog  box  function  (as  discussed  in  Chapter 
10),  obtain  the  pointer  from  MakeProcInstance.  The  function  must  be 
declared  as  FAR  PASCAL  -export. 

Although  these  rules  are  numerous  and  important,  don’t  let  them  drive  you  to 
paranoia.  Keep  in  mind  that  Windows  is  nonpreemptive.  Windows  will  not  pull  the  rug  out 
from  under  you  by  interrupting  your  code.  Windows  can  move  or  discard  your  code  seg¬ 
ments  only  when  you  make  a  far  call.  Windows  will  not  move  your  data  segment  except 
when  you  make  a  few  select  Windows  calls.  If  you  have  a  long  stretch  of  code  between  two 
Windows  calls,  you  can  be  as  carefree  as  you  like  in  that  code  without  worrying  about  sud¬ 
den  movements. 

Program  Segment  Attributes 

I  have  been  talking  about  program  segments  that  are  fixed,  moveable,  and  discardable. 
These  characteristics  are  called  “segment  attributes.”  To  tell  Windows  the  attributes  you 
desire  of  your  program  segments,  you  use  the  CODE,  DATA,  and  SEGMENTS  statements  in 
the  module  definition  file.  During  linking,  LINK  encodes  the  attributes  for  each  program 
segment  in  a  16-bit  flag  and  stores  this  flag  in  the  segment  table  of  the  .EXE  file.  Windows 
has  access  to  these  segment  attributes  when  loading  your  code  and  data  segments.  The 
sample  programs  presented  so  far  contain  these  two  lines  in  their  module  definition  files: 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

We  have  not  yet  encountered  the  SEGMENTS  statement. 

The  CODE  statement  applies  to  all  code  segments  within  your  program  that  are  not 
explicitly  listed  in  the  SEGMENTS  statement.  Similarly,  the  DATA  statement  applies  to  all 
data  segments  except  those  listed  in  the  SEGMENTS  statement. 

There  are  four  standard  attributes:  “load,”  “memory,”  “discardable,”  and  “instance.” 

The  “load”  attribute  can  be  either  PRELOAD  or  LOADONCALL.  This  attribute  tells 
Windows  when  to  load  the  segment.  A  PRELOAD  segment  will  be  loaded  at  the  time  the 
program  begins  execution.  A  LOADONCALL  segment  will  be  loaded  into  memory  the  first 
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time  it  is  needed.  For  a  program  with  a  single  code  module,  it  really  doesn’t  matter  which 
you  use.  For  programs  with  multiple  code  modules,  you  should  use  PRELOAD  for  segments 
that  are  required  when  the  program  first  starts  (for  instance,  those  that  do  initialization 
from  WinMairi)  and  LOADONCALL  for  the  other  code  segments,  particularly  those  that 
will  rarely  be  used.  To  specify  different  attributes  for  multiple  code  segments,  you  must  use 
the  SEGMENTS  statement  discussed  later. 

The  “memory”  attribute  can  be  either  FIXED  or  MOVEABLE.  If  you’re  writing  nor¬ 
mal  Windows  programs,  you  should  have  no  problem  specifying  MOVEABLE.  (Device 
drivers  that  must  process  hardware  interrupts  are  another  matter.  These  usually  require 
one  fixed  code  segment.) 

The  “discardable”  attribute  is  indicated  by  the  DISCARDABLE  keyword.  This  indi¬ 
cates  that  Windows  can  discard  the  segment  from  memory  and  reload  it  from  the  .EXE  file 
when  necessary.  Code  segments  in  normal  Windows  programs  should  be  flagged  as  DIS¬ 
CARDABLE.  The  default  data  segment  cannot  be  flagged  as  DISCARDABLE. 

The  “instance”  attribute  is  relevant  only  for  data  segments.  It  should  be  set  to  MUL¬ 
TIPLE  for  Windows  programs,  indicating  that  each  instance  gets  its  own  data  segments. 
The  NONE  and  SINGLE  options  are  for  Windows  dynamic  link  libraries  (discussed  in 
Chapter  19)  because  Windows  libraries  can  have  only  one  instance.  If  the  Windows  library 
has  a  data  segment,  SINGLE  is  used.  If  not,  NONE  is  used. 

The  SEGMENTS  statement  lets  you  assign  different  segment  attributes  to  other  code 
and  data  segments  within  your  program.  The  general  form  of  the  SEGMENTS  statement  is: 

SEGMENTS  segment-name  [CLASS  'class-name']  [allocate]  [attributes] 

You’ll  probably  use  this  statement  most  often  if  you  create  a  medium-model  program 
or  a  small-model  program  with  multiple  code  segments.  For  a  medium-model  program,  the 
C  library  functions  and  start-up  code  are  in  a  code  segment  named  _TEXT.  Each  source 
code  module  is  assigned  a  different  code  segment  name  that  by  default  is  the  filename  of 
the  source  code  file  followed  by  _TEXT.  For  instance,  if  you  have  three  source  code  mod¬ 
ules  called  PROGRAM. C,  MODULE1.C,  and  MODULE2.C,  the  PROGRAM.EXE  file  has  four 
code  segments:  _TEXT,  PROGRAM -TEXT,  MODULE1  -TEXT,  and  MODULE2 -TEXT. 

If  you  do  not  include  a  SEGMENTS  statement,  all  four  code  modules  take  on  the  at¬ 
tributes  from  the  CODE  statements.  If  you  do  include  a  SEGMENTS  statement,  however, 
your  results  might  look  something  like  this: 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

SEGMENTS  M0DULE1.TEXT  LOADONCALL  MOVEABLE  DISCARDABLE 

M0DULE2JTEXT  LOADONCALL  MOVEABLE  DISCARDABLE 

Now  the  -TEXT  and  PROGRAM-TEXT  segments  are  PRELOAD  and  are  loaded 
when  the  program  first  begins  execution.  MODULEl-TEXT  and  MODULE2-TEXT  are 
LOADONCALL.  Windows  loads  them  only  when  they  are  needed. 
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If  you  use  the  SEGMENTS  statement  for  data  segments,  you  must  include: 

CLASS  ’DATA' 

By  default,  the  class  is  CODE.  You  can  also  add  a  minimum  allocation  size  to  increase 
the  size  of  the  data  segment  when  it’s  loaded  into  memory. 


ALLOCATING  MEMORY  WITHIN  A  PROGRAM 

Programs  often  need  to  dynamically  allocate  blocks  of  memory  for  internal  use.  Windows 
programs  can  allocate  memory  either  from  the  program’s  private  local  heap  or  from  Win¬ 
dows’  global  heap.  Windows  includes  two  sets  of  memory  allocation  functions,  one  set  for 
using  the  local  heap  and  one  for  the  global  heap. 

There  are  certain  trade-offs  between  local  and  global  memory  allocations.  Local 
memory  allocations  are  generally  faster  and  require  less  overhead,  but  the  memory  in  the 
local  heap  is  limited  to  64  KB  less  the  combined  size  of  the  program’s  initialized  static  vari¬ 
ables,  the  program’s  uninitialized  static  variables,  and  the  stack.  Global  memory  alloca¬ 
tions  are  not  limited  to  64  KB,  either  in  the  size  of  single  blocks  or  in  the  total  memory  you 
can  allocate.  However,  pointers  to  global  memory  blocks  are  far  pointers,  which  can  be 
awkward  to  work  with  in  your  program.  (You  cannot  pass  a  far  pointer  to  small-model  and 
medium-model  C  library  functions,  for  instance.)  Also,  in  protected  mode,  a  descriptor 
table  is  limited  to  8,195  entries,  so  no  more  than  8,195  global  segments  may  be  allocated 
throughout  all  of  Windows. 

The  following  table  summarizes  the  differences  between  memory  allocations  from 
the  local  heap  and  the  global  heap: 


Local  Heap 

Global  Heap 

Size  of  block 

Less  than  64  KB 

Any  size 

Total  memory 

Less  than  64  KB 

Free  global  memory 

Pointer 

Near 

Far 

You’ll  probably  find  local-heap  allocations  convenient  for  small,  short-lived  blocks  of 
memory  and  global-heap  allocations  convenient  for  large,  long-lived  blocks. 

The  memory  blocks  you  allocate  can  be  fixed,  moveable,  or  discardable.  You  specify 
the  attributes  you  want  when  you  allocate  the  memory  block.  When  you  write  polite,  well- 
mannered  Windows  programs,  you’ll  want  to  use  moveable  blocks  when  allocating  global 
memory,  but  you  can  use  either  fixed  or  moveable  blocks  for  local  memory. 

Lock  Your  Blocks 

I  mentioned  at  the  outset  of  this  chapter  that  even  Windows  1.0  running  in  real  mode  im¬ 
plemented  moveable  global  memory.  And  even  in  protected  mode,  moveable  local 
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memory  seems  impossible:  When  a  program  allocates  some  local  memory,  Windows  has  to 
give  the  program  a  16-bit  pointer  so  that  the  program  can  access  the  memory.  If  Windows 
later  moves  the  memory  block,  that  pointer  will  be  invalid.  It  will  no  longer  point  to  the 
right  place. 

How  does  Windows  do  it?  The  catch  here  is  that  when  you  allocate  a  block  of  move- 
able  local  memory,  the  memory  allocation  function  does  not  directly  return  a  pointer  that 
the  program  may  use.  Instead,  the  function  returns — as  you  can  probably  guess  by  now — 
a  handle.  WINDOWS.H  defines  a  data  type  called  LOCALHANDLE  (which  is  defined  as 
type  HANDLE,  which  is  a  WORD,  which  is  an  unsigned  16-bit  short  integer).  The  local 
heap  contains  a  table  that  maps  these  handles  to  local  memory  in  the  heap.  Before  your 
program  can  use  the  allocated  memory  block,  it  must  pass  that  handle  back  to  Windows  in 
another  function  that  locks  the  memory  block  and  returns  a  pointer.  When  a  local  memory 
block  is  locked,  Windows  will  not  move  it.  The  pointer  will  continue  to  be  valid  until  you 
call  another  function  to  unlock  the  block.  After  that,  Windows  is  free  to  move  the  memory 
block  again. 

More  precisely,  the  functions  that  lock  a  block  of  memory  increment  a  “lock  count” 
for  the  memory  block.  The  unlocking  functions  decrement  the  lock  count.  When  you  first 
allocate  moveable  local  memory,  the  lock  count  is  0,  meaning  that  Windows  can  move  it  if 
necessary.  When  the  lock  count  is  positive,  Windows  cannot  move  the  block.  (A  lock  count 
is  preferable  to  a  simple  flag  that  denotes  whether  a  block  is  locked,  because  different 
parts  of  your  program  can  independently  lock  a  block,  use  it,  and  unlock  it.  If  Windows 
used  a  flag  instead  of  a  lock  count,  the  memory  block  might  become  unlocked  when  an¬ 
other  section  of  the  program  still  needed  it.) 

In  real  mode,  Windows  works  similarly  for  global  memory.  The  global  memory  allo¬ 
cation  function  returns  a  handle  of  type  GLOBALHANDLE  that  maps  into  an  address.  Tra¬ 
ditionally,  Windows  programmers  were  told  that  global  memory  blocks  should  be  locked 
only  when  the  program  has  control.  The  program  should  unlock  the  block  before  leaving 
the  window  procedure. 

In  protected  mode,  a  global  memory  handle  is  the  selector  of  the  allocated  segment. 
The  strict  rules  for  real  mode  have  been  relaxed.  Because  Windows  can  continue  to  move  a 
locked  block  of  moveable  memory,  a  program  can  lock  a  global  memory  block  immedi¬ 
ately  after  allocating  it. 

A  Quick  Example 

Before  going  into  details,  let’s  look  at  a  quick  example  to  get  the  feel  of  this  process.  With 
the  switch  from  real  mode  to  protected  mode,  the  functions  involved  are  the  same  but  the 
process  is  a  little  different. 

First,  the  real  mode  process . . . 
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Let’s  say  that  your  program  needs  a  48-KB  chunk  of  global  memory  during  the  entire 
time  the  program  is  running.  During  initialization  (for  instance,  when  processing  the 
WM_CREATE  message),  the  program  uses  GlobalAlloc  to  allocate  a  48-KB  segment  of 
moveable  memory: 

hGlobal Memory  =  GlobalAlloc  (GMEM_MOVEABLE.  0xC000L)  ; 

The  value  returned  from  GlobalAlloc  is  a  handle  to  a  48-KB  global  memory  segment.  Store 
the  handle  in  a  static  variable  (here  called  bGlobalMemory). 

While  processing  other  messages,  you  might  need  to  read  from  or  write  to  this 
memory  segment.  At  that  time,  you  lock  the  block  of  memory  using  GlobalLock  and  save 
the  far  pointer  returned  from  that  function: 

IpGlobal Memory  =  GlobalLock  (hGlobalMemory)  ; 

You  can  now  use  the  IpGlobalMemory  pointer  as  a  normal  far  pointer.  When  you  are 
finished  using  the  memory  or  processing  the  message,  unlock  the  segment  so  that  Win¬ 
dows  can  move  it  around  in  memory  again: 

G1 obal Unlock  (hGlobalMemory)  ; 

When  your  program  cleans  up  in  preparing  to  terminate  (probably  when  processing 
the  WM -DESTROY  message),  it  can  free  up  the  memory  segment  by: 

GlobalFree  (hGlobalMemory)  ; 

This  is  how  a  polite,  well-behaved  Windows  program  used  global  memory  in  real 
mode,  and  it  was  something  of  a  hassle.  In  protected  mode,  the  memory  block  can  be 
locked  right  after  it  is  allocated.  For  example: 

IpGlobalMemory  =  GlobalLock  (GlobalAlloc  (GMEM_MOVEABLE ,  0xC000L))  ; 

Indeed,  a  macro  that  does  precisely  this  is  included  in  the  Windows  3.1  header  file 
WINDOWSX.H: 

//define  GlobalAllocPtr(flags,  cb)  \ 

(GlobalLock  (GlobalAlloc  ((flags),  (cb)))) 

So,  you  can  simply  call: 

IpGlobalMemory  =  G1 obal A1 1 ocPtr  (GMEM.MOVEABLE,  0XC000L)  ; 
to  allocate  the  memory  and  later  use  the  GlobalFreePtr  macro  to  free  it: 

Global FreePtr  (IpGlobalMemory)  ; 

Global  Memory  Functions 

Now  for  the  details.  This  is  the  general  syntax  of  the  GlobalAlloc  call: 
hGlobalMemory  =  GlobalAlloc  (wFlags,  dwSize)  ; 
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The  dwSize  parameter  is  a  double  word  (unsigned  long).  This  value  can  be  greater 
than  65,536;  however,  there  are  special  considerations  in  using  global  memory  blocks 
greater  than  64  KB.  (These  will  be  discussed  later.) 

The  wFlags  parameter  can  be  a  combination  of  several  identifiers  that  are  combined 
with  the  C  bitwise  OR  operator.  You  first  have  a  choice  of  three  identifiers  to  define  the  at¬ 
tribute  of  the  allocated  memory  block: 

■  GMEM_FIXED — Memory  is  fixed.  (This  is  the  default  if  wFlags  is  0.) 

■  GMEM_MOVEABLE — Memory  is  moveable. 

■  GMEM_DISCARDABLE — Memory  is  discardable.  This  option  should  be 
used  only  with  GMEM-MOVEABLE.  I’ll  discuss  later  how  you  can 
manage  discardable  global  memory  in  your  programs. 

With  any  of  the  above-mentioned  three  flags,  you  can  use  the  GMEM_ZEROINIT 
flag  for  convenience;  this  flag  tells  Windows  to  initialize  memory  contents  to  0. 

You  can  use  two  more  flags  to  tell  Windows  what  to  do  if  not  enough  free  memory  ex¬ 
ists  in  the  global  heap.  When  Windows  attempts  to  allocate  the  block  requested  by 
GlobalAlloc ,  it  first  searches  to  see  if  a  large  enough  free  block  exists  already.  If  not,  Win¬ 
dows  begins  moving  blocks  of  memory  that  are  moveable  and  not  currently  locked.  If  that 
doesn’t  generate  enough  space,  Windows  begins  discarding  blocks  that  are  marked  as  dis¬ 
cardable  and  not  currently  locked,  again  moving  moveable  unlocked  segments.  You  can  in¬ 
hibit  this  action  by  using  one  of  two  flags: 

■  GMEM_NOCOMPACT — Windows  will  neither  compact  memory  nor 
discard  memory  when  attempting  to  allocate  the  block. 

■  GMEM_NODISCARD — Windows  will  not  discard  discardable  global 
memory  when  attempting  to  allocate  the  block.  Windows  may  still 
compact  memory  by  moving  moveable  blocks. 

If  your  program  implements  Dynamic  Data  Exchange  (DDE),  you’ll  need  to  use  the 
GMEM_DDESHARE  flag  to  allocate  blocks  of  memory  that  can  be  shared  among  multiple 
programs.  I’ll  discuss  this  in  Chapter  17. 

In  almost  all  normal  cases,  you  should  use  the  GMEM_MOVEABLE  flag  when 
allocating  a  global  memory  block  in  protected  mode.  The  only  real  exception  is  for  code  in 
dynamic  link  libraries  that  must  process  hardware  interrupts. 

The  hGlobalMemory  value  returned  from  GlobalAlloc  is  a  handle  to  the  global 
memory  block.  (In  real  mode,  this  handle  is  the  segment  address  if  the  GMEM_FIXED  flag 
was  used.  In  protected  mode,  the  handle  is  always  the  selector.)  The  handle  is  NULL  if 
GlobalAlloc  could  not  allocate  the  requested  memory.  You  should  definitely  check  the 
return  value  from  GlobalAlloc  when  allocating  global  memory. 
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WINDOWS.H  includes  two  shorthand  flags  for  allocating  moveable  or  fixed  memory 
that  is  initialized  to  0.  The  flag  GHND  (which  stands  for  “global  handle”)  is  defined  as: 

GMEM_M0V EAB LE  !  GMEM_ZER0 1 N I T 

The  flag  GPTR  (“global  pointer”)  is  defined  as: 

GMEM_F I X ED  !  GMEM_ZER0 1 N I T 

The  name  of  the  GPTR  flag  refers  to  the  fact  that  the  handle  of  a  fixed  segment  is  the 
segment  address  or  selector. 

The  function  GlobalLock  locks  the  segment  in  memory  by  incrementing  the  lock 
count  and  returns  a  far  pointer  to  type  character.  (Lock  counts  are  not  maintained  for 
moveable  global  memory  in  protected  mode.)  You  should  have  a  variable  declared  for  this 
pointer: 

LPSTR  lpGlobalMemory  ; 

[  other  program  lines  ] 

lpGlobalMemory  =  GlobalLock  (hGlobalMemory)  ; 

If  hGlobalMemory  is  valid,  GlobalLock  can  return  NULL  only  if  you  flagged  the 
memory  block  with  GMEM_DISCARDABLE.  The  NULL  return  value  indicates  that  the 
block  has  been  discarded. 

Because  GlobalLock  is  declared  as  returning  a  far  pointer  to  type  char ;  you  should 
use  casting  if  you  need  something  different: 

DWORD  FAR  *  1 pdwGl obal Memory  ; 

[  other  program  lines  ] 

IpdwGl obal Memory  =  (DWORD  FAR  *)  GlobalLock  (hGlobalMemory)  ; 

The  far  pointer  returned  from  GlobalLock  points  to  the  beginning  of  a  segment.  The 
offset  address  is  0. 

As  I  mentioned  earlier,  the  WINDOWSX.H  header  file  defines  a  macro  that  combines 
the  calls  to  GlobalAlloc  and  GlobalLock.  The  macro  has  the  following  syntax: 

lpGlobalMemory  =  G1 obal A1 1 ocPtr  (wFlags,  dwSize)  ; 

In  protected  mode,  almost  all  your  memory  allocations  can  look  something  like  this: 

lpGlobalMemory  =  G1 obal A1 1 ocPtr  (GHND,  dwSize)  ; 

There  may  also  be  casting  required  if  lpGlobalMemory  is  not  defined  as  a  pointer  to 

char. 

The  GlobalUnlock  function  decrements  the  lock  count  for  the  hGlobalMemory 
handle: 

GlobalUnlock  (hGlobalMemory)  ; 
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For  moveable  memory  in  real  mode,  calling  GlobalUnlock  invalidates  the  Ip- 
GlobalMemory  pointer  returned  from  GlobalLock.  When  the  lock  count  is  0,  Windows  can 
move  the  block  in  memory.  For  moveable  memory  in  protected  mode,  this  function  doesn’t 
do  much  of  anything. 

When  you  are  entirely  finished  with  the  memory  block,  you  can  call: 

GlobalFree  (hGlobalMemory)  ; 

Following  this  call,  the  hGlobalMemory  handle  is  no  longer  valid,  and  the  block  is 

freed. 

The  WINDOWSX.H  header  file  contains  a  macro  that  frees  the  memory  block  using 
the  pointer  rather  than  the  handle: 

Global FreePtr  (lpGlobalMemory)  ; 

If  you  need  to  use  some  functions  that  accept  global  memory  handles  and  macros  that 
require  pointers,  you  can  convert  from  a  pointer  to  the  handle  by  calling  GlobalHandle. 

More  Global  Memory  Functions 

Although  the  four  global  memory  functions  just  discussed  are  the  ones  you’ll  use  most 
often,  Windows  also  provides  several  others.  Before  using  GlobalAlloc ,  you  may  want  to 
determine  the  amount  of  global  memory  currently  available: 

dwAvailable  =  G1 obal Compact  (dwRequested)  ; 

GlobalCompact  causes  Windows  to  move  moveable  blocks  and  to  calculate  the  area 
of  free  memory  that  could  be  obtained  by  also  discarding  discardable  blocks.  If  the  func¬ 
tion  cannot  generate  dwRequested  bytes,  it  returns  the  largest  block  of  free  memory  avail¬ 
able.  Discarding  doesn’t  take  place  until  you  call  GlobalAlloc  using  the  size  returned  from 
GlobalCompact. 

After  you  allocate  a  memory  block,  you  can  determine  its  size  using: 
dwSize  =  GlobalSize  (hGlobalMemory)  ; 

If  you  need  to  determine  the  size  of  a  global  memory  block  from  its  pointer,  you  can 
use  GlobalSize  in  conjunction  with  the  macro  GlobalPtrHandle.  This  macro  uses  the  func¬ 
tion  GlobalHandle  to  obtain  a  handle  from  a  selector: 

dwSize  =  GlobalSize  (GlobalPtrHandle  (lpGlobalMemory))  ; 

You  can  also  change  the  size  of  the  memory  block  or  change  its  attributes  using 
GlobalReAlloc.  This  function  is  a  little  tricky  because  it  can  be  used  in  one  of  three  ways. 
Here’s  the  general  syntax: 

hGlobalMemory  =  GlobalReAlloc  (hGlobalMemory,  dwSize,  wFlags)  ; 


294 


Chapter  7:  Memory  Management 


First,  you  can  change  the  size  of  a  global  memory  block  (either  increasing  or  decreas¬ 
ing  it)  using: 

GlobalReAlloc  (hGl obalMemory ,  dwNewSize,  wFlags)  ; 

The  data  already  stored  in  the  block  are  preserved.  The  function  returns  NULL  if  it 
cannot  increase  the  block  to  the  requested  size. 

The  wFlags  parameter  is  used  the  same  way  as  the  wFlags  parameter  for  GlobalAlloc. 
GMEM_NODISCARD  and  GMEM -NOCOMPACT  place  restrictions  on  what  Windows  will 
do  to  satisfy  the  allocation  request.  GMEM-ZEROINIT  zeroes  out  additional  bytes  if  you 
are  expanding  the  block.  When  calling  GlobalReAlloc ,  you  don’t  have  to  include  the 
GMEM-FIXED,  GMEM -MOVEABLE,  or  GMEM -DISCARDABLE  flags.  Windows  preserves 
the  attribute  specified  when  the  block  was  allocated.  However,  you  may  want  to  use  the 
GMEM-MOVEABLE  flag  for  reallocating  a  fixed  block.  Doing  so  gives  Windows  permis¬ 
sion  to  move  the  block  in  memory  to  satisfy  the  allocation  request.  In  this  case, 
GlobalReAlloc  returns  a  new  global  memory  handle  to  the  fixed  block: 

hGlobalMemoryNew  =  GlobalReAlloc  (hGl obal MemoryOl d ,  dwNewSize,  GMEM_MOVEABLE)  ; 

If  GlobalReAlloc  returns  NULL,  the  request  for  memory  was  refused,  and  the  original 
hGlobalMemoryOld  value  passed  to  GlobalReAlloc  is  still  valid  for  the  block. 

The  second  way  to  use  GlobalReAlloc  is  to  change  the  discardable  attribute  of  move- 
able  blocks.  The  dwNewSize  value  is  ignored.  You  can  change  a  moveable  block  to  a  dis¬ 
cardable  one: 

GlobalReAlloc  (hGl obal Memory ,  0L,  GMEM_M0DI FY  !  GMEM_DI SCARDABLE )  ; 
or  change  a  discardable  block  to  a  moveable  (but  nondiscardable)  one: 

GlobalReAlloc  (hGl obal Memory ,  0L,  GMEM_M0DI FY  !  GMEM_M0V EABLE )  ; 

The  third  use  of  GlobalReAlloc  is  to  discard  a  discardable  memory  block.  This  re¬ 
quires  dwNewSize  to  be  0  and  the  wFlags  parameter  to  be  GMEM -MOVEABLE: 

GlobalReAlloc  (hGlobalMemory ,  0L,  GMEM_M0V EABLE)  ; 

You  can  do  the  same  thing  using: 

G1 obal Di sea rd  (hGlobalMemory)  ; 

In  fact,  GlobalDiscard  is  a  macro  defined  in  terms  of  GlobalReAlloc. 

The  WINDOWSX.H  header  file  contains  a  macro  that  lets  you  reallocate  memory 
based  on  the  pointer  rather  than  the  handle: 

lpGlobalMemoryNew  =  G1  obal ReAl  1  ocPtr  ( 1 pGl obal Memory ,  dwSize,  wFlags)  ; 
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Using  Discardable  Global  Memory 

Discardable  memory  segments  are  generally  used  for  data  that  can  be  easily  regenerated. 
For  example,  suppose  you  decide  to  use  a  separate  file  for  “help”  text  that  your  program 
displays  when  the  user  requests  it.  You  could  allocate  a  moveable  block,  lock  it,  read  a 
chunk  of  data  from  the  file,  display  it  to  the  screen,  unlock  the  block,  and  free  it.  However, 
this  approach  requires  that  your  program  allocate  a  new  block  of  memory  and  access  this 
file  every  time  help  information  is  requested. 

Alternatively,  you  could  keep  a  moveable  block  for  this  file  buffer  in  memory  all  the 
time.  When  the  user  requests  some  help  information,  you  check  to  see  that  the  information 
is  already  in  the  buffer,  and  then  you  use  that  information  rather  than  access  the  disk  again. 
The  performance  of  your  program  improves,  but  it  does  so  at  the  cost  of  having  a  block  of 
global  memory  allocated  for  the  duration  of  your  program. 

How  about  using  a  discardable  block  instead?  This  keeps  the  buffer  in  memory  but 
also  gives  Windows  permission  to  discard  it  if  necessary.  When  you  lock  the  block: 

lpGlobal Memory  =  G1 oba 1  Lock  (hGlobalMemory)  ; 

the  IpGlobalMemory  return  value  will  be  NULL  if  the  block  has  been  discarded.  In  that 
case,  you  use  GlobalReAlloc  to  reallocate  the  segment.  Windows  never  discards  a  discard¬ 
able  block  when  the  lock  count  is  nonzero. 

If  you  have  obtained  a  valid  far  pointer  from  GlobalLock,  that  pointer  is  valid  until  you 
call  GlobalUnlock.  Even  after  the  block  is  discarded,  the  handle  is  still  valid.  (This  avoids 
problems  when  you  pass  the  handle  to  GlobalLock .) 

You  can  also  determine  that  a  block  is  discardable  or  has  been  discarded  by  using  the 
GlobalFlags  function: 

wFlags  =  GlobalFlags  (hGlobalMemory)  ; 

WINDOWS.H  has  identifiers  you  can  use  in  combination  with  wFlags.  This  value  is 
nonzero  if  the  block  is  discardable: 

( GMEM_DI SCARDAB LE  &  wFlags) 

This  value  is  nonzero  if  the  block  has  been  discarded: 

( GMEM_DI SCARDED  &  wFlags) 

Another  approach  is  to  include  the  GLOBAL_NOTIFY  flag  when  allocating  a  discard¬ 
able  segment.  In  this  case,  Windows  will  call  a  call-back  function  in  your  program  that  has 
been  registered  with  the  GlobalNotify  function  when  it  is  about  to  discard  a  discardable 
segment. 

Huge  Global  Memory  Blocks 

The  dwSize  parameter  in  GlobalAlloc  is  a  32-bit  DWORD  (double  word),  large  enough  in 
theory  to  allocate  a  4-GB  block  of  memory.  Although  you  obviously  won’t  be  able  to  get  a 
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block  quite  that  large,  the  syntax  of  the  function  implies  that  you  can  still  allocate  a  block 
of  memory  larger  than  64  KB.  Yes,  you  can,  but  you  have  to  be  careful.  Beginning  with  ver¬ 
sion  4.0  of  the  Microsoft  C  Compiler,  the  huge  keyword  was  implemented  for  defining  vari¬ 
ables  that  are  larger  than  64  KB.  A  huge  pointer  is  32  bits,  just  like  a  far  pointer.  However, 
16-bit  C  compilers  assume  that  a  far  pointer  addresses  only  a  64-KB  range  and  will  never 
run  past  the  end  of  the  segment.  With  a  huge  pointer,  a  compiler  generates  code  that 
checks  for  segment  overrun  and  does  appropriate  segment  arithmetic  on  the  pointer. 

The  term  “segment  arithmetic”  should  have  triggered  an  alarm  in  your  head!  I  men¬ 
tioned  earlier  that  you  should  not  perform  segment  arithmetic  in  your  Windows  programs 
because  it  violates  the  rules  of  protected  mode.  Fortunately,  the  Microsoft  and  Borland 
compilers  and  Windows  work  together  to  perform  different  segment  arithmetic  depending 
on  whether  the  program  is  running  in  real  mode  or  protected  mode.  In  real  mode,  jumping 
from  the  end  of  one  64-KB  segment  to  the  beginning  of  another  segment  requires  adding 
0x1000.  In  protected  mode,  the  selectors  are  allocated  so  that  8  is  added  for  the  segment 
jump.  Windows  defines  two  constants  named  -AHSHIFT  and  _AHINCR  that  allow  a  pro¬ 
gram  to  obtain  these  values. 

When  you  use  GlobalAlloc  to  allocate  memory  greater  than  64  KB,  you  must  cast  the 
pointer  returned  from  GlobalLock  into  a  huge  pointer  and  save  it  as  a  huge  pointer.  For  in¬ 
stance,  this  code  allocates  a  128-KB  memory  block  and  locks  it: 

char  huge  *  1 pGl obalMemory  ; 

[  other  program  lines  ] 

lpGl obalMemory  =  (char  huge  *)  G1 obal A1 1 ocPtr  (GMEM_MOVEABLE,  0x20000L)  ; 

Every  function  that  manipulates  this  huge  pointer  must  be  aware  that  the  pointer  is 
huge.  If  a  function  that  is  passed  a  huge  pointer  believes  that  the  pointer  is  a  simple  far 
pointer,  the  compiler  will  not  generate  any  segment  arithmetic  when  you  manipulate  the 
pointer.  For  this  reason,  you  should  not  pass  a  huge  pointer  to  most  of  the  standard  C 
library  functions  (the  compiler  manuals  list  functions  that  support  huge  arrays)  or  to  most 
Windows  functions  unless  you  know  that  the  function  will  not  be  referencing  the  pointer 
past  the  end  of  a  segment. 

That’s  one  problem  with  huge  pointers.  Another  problem  is  the  possibility  that  a 
single  data  item  referenced  by  the  pointer  may  straddle  two  segments.  With  a  huge  pointer 
to  character  data,  this  is  never  a  problem  because  each  character  is  a  byte.  The  offset  ad¬ 
dress  that  GlobalLock  returns  is  always  0,  so  the  huge  pointer  can  also  safely  reference 
arrays  of  all  the  standard  data  types  (char,  short,  int,  long,  float,  and  double). 

If  you  use  a  huge  pointer  to  an  array  of  structures,  you  will  have  no  problems  if  the 
size  of  the  structure  is  a  power  of  2  (such  as  2,  4,  8, 16,  and  so  forth)  because  that  guaran¬ 
tees  that  no  single  structure  will  straddle  two  segments.  If  the  size  of  the  structure  is  not  a 
power  of  2,  then  you  are  bound  by  two  restrictions: 
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■  The  data  block  allocated  with  GlobalAlloc  cannot  be  larger  than  128  KB. 

■  The  offset  address  returned  from  GlobalLock  must  be  adjusted  so  that  a 
structure  does  not  straddle  two  segments. 

The  first  rule  is  actually  implied  by  the  second  rule.  If  the  initial  offset  address  is  ad¬ 
justed  so  that  an  element  of  the  structure  does  not  straddle  the  first  and  second  segments, 
it  will  straddle  the  second  and  third  segments. 

This  explanation  requires  an  example.  Let’s  say  you  want  a  huge  memory  block  to 
hold  an  array  of  15,000  structures,  and  each  structure  requires  6  bytes.  You  can  use  typedef 
statements  for  this  structure  and  a  far  pointer  to  the  structure: 

typedef  struct 

{ 

int  el  emeriti  ; 
long  element2  ; 

} 

MYSTRUCT  ; 

typedef  MYSTRUCT  huge  *  LPMYSTRUCT  ; 

In  your  program,  you  can  define  a  variable  for  the  far  pointer  to  the  structure: 

LPMYSTRUCT  lpMyStruct  ; 

[  other  program  lines  ] 

lpMyStruct  =  (LPMYSTRUCT)  ((65536L  %  sizeof  (MYSTRUCT) )+ 

GlobalAllocPtr  (GHND,  15001  *  sizeof  (MYSTRUCT)))  ; 

The  pointer  returned  from  GlobalAllocPtr  will  have  an  offset  address  of  0.  You  must 
increase  that  so  that  a  single  structure  does  not  straddle  the  two  segments.  The  adjustment 
value  is  the  remainder  of  65,536  divided  by  the  size  of  the  structure.  (In  this  case,  the  ad¬ 
justment  value  is  4.)  Because  you  have  a  little  waste  here,  GlobalAlloc  allocates  one  more 
structure  than  is  really  needed. 

Allocating  Local  Memory 

I’ve  been  stressing  the  importance  of  using  moveable  (and,  if  possible,  discardable)  global 
memory  blocks.  With  local  memory  you  have  the  same  options,  but  the  guidelines  are  more 
relaxed.  Whether  you  use  fixed  or  moveable  memory  blocks  within  your  local  heap  is  up  to 
you.  Because  your  entire  data  segment  is  moveable  (as  it  will  be  if  you  use  the  small  or 
medium  model),  what  you  do  inside  your  data  segment  doesn’t  affect  other  applications 
very  much. 

In  fact,  Windows  makes  it  easier  to  use  local  memory  if  the  blocks  are  fixed.  The 
question  you  have  to  ask  yourself  is  this:  Can  my  local  heap  be  smaller  if  I  use  moveable 
blocks  instead  of  fixed  blocks?  If  you  use  local  memory  a  lot  and  if  the  life  spans  of  the 
memory  blocks  overlap  each  other,  then  the  answer  to  that  question  may  be  “yes.”  If  you 
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use  local  memory  allocations  solely  for  short-lived  memory,  however,  there’s  no  reason  to 
make  the  blocks  moveable. 

The  local  memory  functions  are  similar  to  the  global  memory  functions.  Instead  of 
GlobalAlloc ,  GlobalLock ,  GlobalUnlock,  and  GlobalFree,  you  use  LocalAlloc,  LocalLock, 
LocalUnlock,  and  LocalFree.  Instead  of  identifiers  that  begin  with  GMEM,  you  use  iden¬ 
tifiers  that  begin  with  LMEM.  The  only  real  differences  are  these:  The  memory  size  passed 
to  LocalAlloc  is  a  WORD  (unsigned  integer)  rather  than  a  DWORD,  and  the  pointer 
returned  from  LocalLock  is  a  near  pointer  rather  than  a  far  pointer. 

This  is  the  syntax  of  LocalAlloc. 

hLocalMemory  =  LocalAlloc  (wFlags,  wSize)  ; 

The  wSize  parameter  is  large  enough  to  accommodate  a  requested  size  of  65,536 
bytes,  but  you  won’t  get  a  local  block  that  large  because  the  data  segment  also  includes 
your  program’s  stack  and  static  variables. 

The  wFlags  parameter  can  first  specify  the  attributes  of  the  block: 

■  LMEM_FIXED — Memory  is  fixed.  (This  is  the  default  if  wFlags  is  0.) 

■  LMEM_MOVEABLE — Memory  is  moveable. 

■  LMEM_DISCARDABLE — Memory  is  discardable.  This  option  should  be 
used  only  with  LMEM -MOVEABLE. 

■  LMEM_ZEROINIT — Zeroes  out  the  memory  block. 

These  two  flags  are  equivalent  to  the  similar  flags  for  GlobalAlloc. 

■  LMEM -NOCOMPACT — Windows  will  neither  compact  nor  discard 
memory  in  the  local  heap  when  attempting  to  allocate  the  block. 

■  LMEM-NODISCARD — Windows  will  not  discard  discardable  memory  in 
the  local  heap  when  attempting  to  allocate  the  block.  Windows  may  still 
compact  memory  by  moving  moveable  blocks. 

WINDOWS.H  also  includes  two  shorthand  flags  for  local  memory  allocations.  The 
flag  LHND  (which  stands  for  “local  handle”)  is  defined  as: 

LMEM_M0V  EABLE  !  LMEM_ZER0 1 N I T 
The  flag  LPTR  (“local  pointer”)  is  defined  as: 

LMEM_FI X ED  !  LMEM_Z ERO I N I T 

If  Windows  cannot  find  enough  memory  in  the  local  heap  to  allocate  the  block,  it  will 
attempt  to  expand  the  local  heap  by  enlarging  the  size  of  the  entire  data  segment.  (Remem¬ 
ber  that  the  local  heap  is  always  at  the  top  of  the  automatic  data  segment.)  Windows  may 
even  move  the  data  segment  to  another  location  in  memory  if  that  will  provide  the  space  it 
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needs  to  expand  the  local  heap.  When  LocalAlloc  returns,  your  data  segment  may  have 
been  moved.  (If  this  makes  you  nervous,  see  the  section  later  in  this  chapter  entitled 
“Locking  Your  Own  Data  Segment.”)  The  HEAPSIZE  specification  in  the  module  defini¬ 
tion  (.DEF)  file  is  really  a  minimum  value  for  the  heap. 

If,  after  all  this,  Windows  still  cannot  find  enough  memory  in  the  local  heap  to  allo¬ 
cate  the  memory  block,  the  handle  returned  from  LocalAlloc  will  be  NULL.  If  you  use  local 
memory  allocation  only  for  small,  short-lived  memory  blocks,  you  probably  don’t  need  to 
check  the  handle  for  a  NULL  value.  (Alternatively,  you  might  want  to  check  the  value  dur¬ 
ing  program  development  but  not  in  the  final  version  of  the  program.)  If  you  do  a  lot  of  ran¬ 
dom  local  memory  allocation  with  blocks  of  various  sizes  and  different  life  spans,  you’ll 
have  to  implement  some  kind  of  error  processing. 

LocalLock  turns  the  local  memory  handle  into  a  near  pointer  and  then  locks  the 
block.  LocalUnlock  unlocks  the  block  and  invalidates  the  pointer.  LocalFree  frees  the 
memory  block  and  invalidates  the  handle. 

Here’s  an  example  of  using  local  memory  to  define  the  window  class  structure  during 
program  initialization: 

LOCALHANDLE  hLocal Memory  ; 

NPWNDCLASS  npwndclass  ; 

[other  program  lines] 

if  ( IhPrevInstance) 

{ 

hLocal Memory  =  LocalAlloc  ( LHND,  sizeof  (WNDCLASS) )  ; 
npwndclass  =  (NPWNDCLASS)  LocalLock  (hLocal Memory)  ; 

npwndcl ass->styl e  =  CS_H REDRAW  !  CS.VREDRAW  ; 

npwndclass->lpfnWndProc  =  WndProc  ; 
npwndclass->cbClsExtra  =  0  ; 
npwndclass->cbWndExtra  =  0  ; 
npwndclass->hlnstance  =  hlnstance  ; 

npwndcl ass->hIcon  =  Loadlcon  (NULL,  IDI.APPLICATION)  ; 

'  npwndclass->hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 
npwndclass->hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
npwndcl ass - >1 pszMenuName  =  NULL  ; 
npwndcl a s s - >1 pszCl assName  =  szAppName  ; 

RegisterClass  (npwndclass)  ; 

LocalUnlock  (hLocal Memory )  ; 

LocalFree  (hLocalMemory)  ; 

The  size  of  the  memory  block  passed  to  LocalAlloc  is  the  size  of  the  WNDCLASS 
structure.  LocalLock  always  returns  a  near  pointer  regardless  of  the  memory  model  be¬ 
cause  it  allocates  memory  from  the  local  heap  in  the  program’s  automatic  data  segment.  In 
this  example,  the  pointer  to  type  character  that  LocalLock  returns  is  cast  into  a  pointer  to  a 
WNDCLASS  structure.  The  ->  notation  is  used  to  reference  the  elements  of  a  structure 
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based  on  a  pointer  to  the  structure.  In  the  RegisterClass  call,  we  don’t  use  the  address  (&) 
operator  because  npwndclass  is  already  a  pointer.  Notice  also  that  the  use  of  LHND  initial¬ 
izes  the  block  of  memory  to  0.  All  variables  in  the  structure  that  take  a  0  or  NULL  value 
need  not  be  explicitly  assigned. 

Other  Local  Memory  Functions 

Some  other  local  memory  functions  parallel  those  for  global  memory  allocations  except 
that  sizes  are  in  terms  of  wSize  rather  than  dwSize.  You  can  get  the  current  size  of  a  local 
memory  block  by  calling: 

wSize  =  LocalSize  ( h Local  Memory)  ; 

The  function  LocalReAlloc  can  change  the  size  of  an  allocated  memory  block,  change 
a  moveable  block  to  discardable,  change  a  discardable  block  to  nondiscardable,  and 
discard  a  discardable  block,  just  like  GlobalReAlloc.  During  a  LocalReAlloc  call,  Windows 
may  expand  the  size  of  the  local  heap  by  expanding  the  size  of  the  entire  data  segment, 
possibly  moving  it  to  another  location  in  memory.  LocalCompact  can  determine  the 
amount  of  free  local  memory  available  in  the  heap,  LocalDiscard  discards  a  discardable 
memory  block,  and  LocalFlags  provides  the  current  status  of  discardable  blocks. 

Two  other  local  memory  functions  do  not  have  counterparts  in  the  global  memory 
functions.  You  can  prevent  your  local  heap  from  being  compacted  by  calling: 

Local  Freeze  (0)  ; 

When  you  later  want  to  allow  compacting,  you  can  call: 

LocalMelt  (0)  ; 

Locking  Your  Own  Data  Segment 

Now  that  you  are  thoroughly  paranoid  about  locking  and  unlocking  memory  blocks,  you 
may  start  to  wonder  about  the  automatic  data  segment  of  the  program  itself.  When  the  pro¬ 
gram  begins  executing,  your  automatic  data  segment  has  a  lock  count  of  1,  and  the  data 
segment  cannot  be  moved  in  memory.  Windows  decrements  that  lock  count  when  the  pro¬ 
gram  makes  one  of  the  following  calls:  GetMessage,  PeekMessage ,  Wait  Message,  LocalAlloc , 
or  LocalReAlloc . 

The  GetMessage ,  PeekMessage ,  and  WaitMessage  calls  can  cause  a  switch  from  your 
program  to  another  program.  When  your  program  gets  control  again,  your  data  segment 
may  have  been  moved.  A  LocalAlloc  or  LocalReAlloc  call  can  cause  Windows  to  expand  the 
size  of  your  local  heap,  in  the  process  moving  the  data  segment  to  another  location  in 
memory.  Windows  increments  the  lock  count  when  it  returns  from  these  calls  to  your  pro¬ 
gram.  So  in  most  cases,  your  program’s  data  segment  is  locked  when  your  program  has 
control.  This  means  that  you  can  construct  (through  casting)  far  pointers  to  data  in  your 
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data  segment,  and  they  will  remain  valid  until  you  make  one  of  these  five  calls  or  exit  the 
window  procedure. 

In  protected  mode,  any  movement  of  your  data  segment  is  not  a  problem.  However,  if 
you  want  to  prevent  it  in  real  mode  during  a  LocalAlloc  or  LocalReAlloc  call,  you  can  in¬ 
crease  the  lock  count  by  1  before  calling  the  function: 

LockData  (0)  ; 

Following  the  LockData  call,  the  lock  count  of  your  data  segment  will  be  2.  When 
Windows  decrements  the  count  during  a  LocalAlloc  or  LocalReAlloc  call,  it  will  still  be 
positive  and  your  data  segment  will  still  be  locked.  You  can  decrement  the  lock  count  by 
calling: 

UnlockData  (0)  ; 

Memory  Allocation  Shortcuts 

We  have  been  treating  handles  as  abstract  numbers,  but  sometimes  handles  are  actually 
pointers.  If  you  use  LMEM_FIXED  in  LocalAlloc ,  the  handle  returned  from  the  call  is  a 
near  pointer  that  you  can  use  directly.  You  do  not  need  to  call  LocalLock.  (If  you  do,  it 
simply  returns  the  same  value  you  pass  as  a  parameter — the  handle  that  is  actually  a  valid 
near  pointer.)  In  fact,  WINDOWS. H  defines  a  special  flag  for  calling  LocalAlloc  with  an 
LMEM-FIXED  parameter.  The  flag  is  LPTR  (“local  pointer”)  and  is  defined  as: 

LMEM_FI X ED  !  LM EM_Z E RO I N I T 

When  you  use  this  flag,  you  need  only  cast  the  return  value  from  LocalAlloc  into  a 
near  pointer  of  the  type  you  want: 

npString  =  (char  NEAR  *)  LocalAlloc  (LPTR,  wSize)  ; 

You  free  it  up  by  casting  the  near  pointer  back  to  a  handle  and  calling  LocalFree. 

Local  Free  ( ( LOCALHANDLE)  npString)  ; 

This  technique  is  handy  for  allocating  small  chunks  of  local  memory.  For  instance, 
here’s  the  example  shown  on  page  300  for  allocating  memory  for  the  window  class  struc¬ 
ture.  It  now  uses  a  fixed  block  of  local  memory: 

NPWNDCLASS  npwndclass  ; 

[other  program  lines] 

if  ( IhPrevInstance) 

{ 

npwndclass  =  (NPWNDCLASS)  LocalAlloc  (LPTR,  sizeof  (WNDCLASS) )  ; 

npwndcl ass->styl e  =  CS_H REDRAW  !  CS.VREDRAW  ; 

npwndcl ass ->1 pfnWndProc  =  WndProc  ; 
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npwndcl ass ->cbCl  s Extra 
npwndcl ass ->cbWnd Extra 
npwndcl ass->hlnstance 
npwndclass->hIcon 
npwndclass->hCursor 


=  0 


hlnstance  ; 

Loadlcon  (NULL,  IDI_APPLICATION) 
=  LoadCursor  (NULL,  IDC.ARROW)  ; 
npwndclass->hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
npwndclass->lpszMenuName  =  NULL  ; 
npwndclass->lpszClassName  =  szAppName  ; 


RegisterClass  (npwndclass) 


Local  Free  ( ( LOCALHANDLE)  npwndclass)  ; 

We’ve  eliminated  two  lines  of  code  (the  LocalLock  and  LocalUnlock )  and  one  vari¬ 
able  (the  local  memory  handle).  Notice  the  casting  in  the  LocalAlloc  and  LocalFree  calls. 


Using  C  Memory  Allocation  Functions 

The  start-up  code  that  the  linker  attaches  to  C  programs  running  under  Windows  contains 
functions  for  many  of  the  standard  C  memory  allocation  functions,  such  as  calloc,  malloc , 
realloc ,  and  free.  The  routines  in  the  start-up  code  convert  the  normal  C  memory  alloca¬ 
tion  functions  into  equivalent  Windows  memory  allocation  functions.  For  instance,  the 
function: 

malloc  (wSize) 
is  translated  into: 

LocalAlloc  ( LMEM_FIXED  !  LM EM_N0C0M P ACT ,  min  (1,  wSize))  ; 

These  functions  are  included  in  the  Windows  start-up  code — not  for  your  benefit  but 
because  several  other  C  functions  from  the  standard  library  make  calls  to  these  C  memory 
allocation  functions.  These  other  C  functions  cannot  work  properly  without  using  the  Win¬ 
dows  memory  allocation  calls.  Although  it’s  not  intended  that  you  use  these  functions,  you 
can  certainly  use  them.  Be  aware,  however,  that  in  compact-memory  and  large-memory 
models  (which  you  shouldn’t  be  using  for  Windows  programs  anyway),  the  Windows 
malloc  returns  a  far  pointer  to  your  program’s  automatic  data  segment — as  opposed  to  the 
non-Windows  malloc ,  which  returns  a  far  pointer  to  a  block  of  memory  outside  the  auto¬ 
matic  data  segment.  Also  be  aware  that  -fmalloc  and  halloc  are  translated  into 
GlobalAlloc  calls  with  a  flag  that  is  equal  to  (GMEM_FIXED  !  GMEM_NODISCARD)  and 
that  (as  you  know)  you  should  not  use  fixed  global  memory  blocks.  Moreover,  the  pointer 
returned  from  the  Windows  halloc  is  not  properly  aligned  for  an  array  of  elements  that  are 
not  multiples  of  2,  and  the  memory  is  not  initialized  to  0. 
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Icons,  Cursors, 
Bitmaps,  and 
Strings 


Most  Windows  programs  include  a  customized  icon  that  Windows  displays  when  the  pro¬ 
gram  is  minimized.  Some  programs  (such  as  the  Windows  PAINTBRUSH  program)  also 
use  customized  cursors  to  represent  different  operations  of  the  program.  Most  Windows 
programs  also  use  menus  and  dialog  boxes. 

Icons,  cursors,  menus,  and  dialog  boxes  are  all  examples  of  “resources.”  Resources 
are  data  and  are  included  in  a  program’s  .EXE  file,  but  they  do  not  reside  in  a  program’s 
normal  data  segment.  When  Windows  loads  a  program  into  memory  for  execution,  it  usu¬ 
ally  leaves  the  resources  on  disk.  Only  when  Windows  needs  a  particular  resource  does  it 
load  the  resource  into  memory.  (You’ve  probably  noticed  dynamic  loading  of  resources 
when  working  with  Windows  programs.  When  you  invoke  a  program’s  dialog  box  for  the 
first  time,  Windows  usually  accesses  the  disk  to  copy  the  dialog  box  resource  from  the  pro¬ 
gram’s  .EXE  file  into  memory.) 

Most  resources  are  read-only  data  and  are  marked  as  discardable.  If  Windows  runs 
out  of  memory,  segments  occupied  by  discardable  resources  can  be  freed  up.  If  the 
resource  is  required  again  later,  Windows  reloads  it  from  the  .EXE  file.  Just  as  multiple 
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instances  of  the  same  program  share  the  same  code,  multiple  instances  also  usually  share 
resources.  I’ll  be  discussing  these  resources: 

■  Icons 

■  Cursors 

■  Bitmaps 

■  Character  strings 

■  User-defined  resources 

■  Menus 

■  Keyboard  accelerators 

■  Dialog  boxes 

■  Fonts 

The  first  five  resources  in  the  list  are  discussed  in  this  chapter.  Menus  and  keyboard  ac¬ 
celerators  are  covered  in  Chapter  9,  dialog  boxes  in  Chapter  10,  and  fonts  in  Chapter  14. 

COMPILING  RESOURCES 

During  program  development,  resources  are  defined  in  a  “resource  script,”  which  is  an 
ASCII  text  file  with  the  extension  .RC.  The  resource  script  can  contain  ASCII  representa¬ 
tions  of  resources  and  can  also  reference  other  files  (either  ASCII  or  binary  files)  that  con¬ 
tain  resources.  The  resource  compiler  (RC.EXE)  compiles  the  resource  script  into  binary 
form,  adds  the  resources  to  the  end  of  the  .EXE  file  that  the  linker  generates,  and  creates  a 
“resource  table”  in  the  .EXE  header. 

You  can  use  the  resource  compiler  in  one  of  three  ways: 

■  You  can  compile  resources  and  add  them  to  the  linked  .EXE  file  in  one 
step  by  executing  the  command: 

RC  filename 

where  filename. RC  is  the  name  of  the  resource  script  (the  .RC  extension 
is  assumed)  and  filename.EXE  is  the  name  of  the  linked  .EXE  file.  You 
can  also  use: 

RC  resource-name  exe-name 

if  the  name  of  your  .RC  resource  script  and  the  name  of  your  .EXE  execut¬ 
able  are  different.  (This  is  usually  not  the  case.) 
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■  You  can  compile  a  .RC  resource  script  into  a  binary  compiled  form  with 
the  extension  .RES  by  executing: 

RC  -r  filename 

This  uses  the  ASCII  filename.RC  file  to  create  a  binary  file  called 
filename.RES.  You  can  then  add  the  resources  to  the  linked  file  by 
executing: 

RC  filename.RES 

The  .RES  extension  is  required  here  to  differentiate  this  command 
from  the  command  shown  earlier  that  both  compiles  the  resource  script 
and  adds  the  resources  to  the  .EXE  file. 

■  If  your  program  has  no  resources,  you  should  run  rc.exe  on  the  linked  file: 

RC  filename.EXE 

This  flags  the  program  as  being  “Windows  3  aware.” 

The  second  method  is  the  one  most  commonly  used  when  a  program  includes 
resources.  Although  it  requires  that  the  RC.EXE  resource  compiler  be  run  twice — once  to 
compile  the  resource  script  and  again  to  add  the  resources  to  the  .EXE  file — it  results  in  a 
faster  edit-make-run  cycle  when  developing  Windows  programs,  because  compiling  the 
resources  generally  takes  much  longer  than  adding  them  to  the  .EXE  file.  During  program 
development,  you’ll  probably  modify  your  C  source  code  much  more  frequently  than  the 
resource  script,  so  you  have  no  need  to  recompile  the  resources  each  time. 

The  procedure  of  compiling  resources  is  reflected  in  a  different  make  file.  Up  until 
now  we  have  been  using  a  make  file  that  looks  something  like  this  (assuming  you’re  using 
the  Microsoft  compiler): 

progname.exe  :  progname.obj  progname.def 

link  /nod  progname,  progname,  NUL,  slibcew  oldnames  libw  commdlg  ddeml , 
progname  rc  -t  progname.exe 

progname.obj  :  progname. c 

cl  -c  -G2sw  -Ow  -W3  -Zp  -Tp  progname. c 

When  we  start  using  resources,  generally  we’ll  use  an  expanded  make  file  that  looks 
like  this: 

progname.exe  :  progname.obj  progname.def  progname. res 

link  /nod  progname,  progname,  NUL,  slibcew  oldnames  libw  commdlg  ddeml, 
progname  rc  -t  progname. res 

progname.obj  :  progname. c  [progname. h] 

cl  -c  -G2sw  -Ow  -W3  -Zp  -Tp  progname. c 

progname. res  :  progname. rc  [progname. h]  [and  other  files] 
rc  -r  progname. rc 
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In  the  second  and  third  sections  I’ve  indicated  that  a  .H  header  file  can  be  used  in  both  the 
C  source  code  and  the  resource  script.  This  header  file  usually  defines  identifiers  used  by 
the  program  to  reference  resources.  I’ve  also  indicated  in  the  third  section  that  the  depen¬ 
dent  file  list  possibly  includes  “other  files.”  These  are  files  referenced  from  within  the 
resource  script.  Generally  they  are  binary  files  that  contain  icons,  cursors,  or  bitmaps. 

The  RC.EXE  resource  compiler  uses  a  preprocessor  called  RCPP.EXE.  This  pre¬ 
processor  folds  added  or  subtracted  constants,  recognizes  Aand  */ as  comment  delimiters, 
and  recognizes  the  C  preprocessor  directives  #define,  #undef,  #ifdef  #ifndef  #include, 
#if,  #elif,  #else,  and  #endif.  The  ^include  directive  works  a  little  differently  than  in  normal 
C  programs.  We’ll  examine  this  in  greater  detail  in  Chapter  10. 

In  the  first  section  of  the  make  file,  the  .OBJ  and  .RES  files  are  dependent  files  for  the 
.EXE  target.  NMAKE  or  MAKE  checks  the  rest  of  the  make  file  to  determine  if  these  depen¬ 
dent  files  must  be  updated.  The  second  section  compiles  the  C  source  code  as  usual.  The 
third  section  compiles  the  .RC  resource  script  into  a  binary  .RES  file. 

The  first  section  is  then  executed  if  either  the  .OBJ,  .DEF,  or  .RES  file  has  changed 
since  the  last  .EXE  file  was  created.  This  section  links  the  program  as  usual  and  runs  .RC 
again  to  add  the  resources  to  the  .EXE  file.  If  you  change  only  the  .RC  resource  script  file, 
you  still  need  to  relink  to  produce  a  new  .EXE  file  without  the  previous  resources.  The 
resource  compiler  cannot  remove  old  resources  from  a  .EXE  file  when  adding  new  ones. 

In  some  cases  (particularly  when  a  dialog  box  template  is  included  in  the  resource 
script),  you  may  need  to  include  WINDOWS.H: 

#include  <windows.h> 

Normally  the  resource  compiler  uses  the  pathnames  in  your  INCLUDE  environment 
variable  to  locate  the  WINDOWS.H  file.  However,  because  the  Borland  C++  Compiler 
doesn’t  use  environment  variables,  users  of  this  compiler  don’t  have  the  INCLUDE  environ¬ 
ment  variable  that  the  resource  compiler  requires.  In  this  case,  you  can  use  the  -i  flag  on 
the  resource  compiler  to  indicate  the  directory  in  which  WINDOWS.H  is  located.  When 
compiling  resources  using  the  Borland  tools,  the  command  line  looks  something  like  this: 

rc  -r  -i \borl andc\i ncl ude  program. rc 

The  resource  compiler  also  serves  another  function:  It  can  set  certain  bits  in  the 
header  of  the  .EXE  file  that  Windows  can  examine  when  it  loads  the  program  for  execu¬ 
tion.  Probably  the  most  important  of  these  flags  is  -t.  This  indicates  that  your  program  runs 
only  in  protected  mode.  If  this  is  true,  you  should  use  the  -t  flag  on  the  resource  compiler 
command  line  when  adding  the  resources  to  the  program  following  the  link: 

rc  -t  programmes 
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If  your  program  runs  only  in  protected  mode  but  does  not  use  resources,  you  must  in¬ 
clude  the  -t  flag  when  running  the  resource  compiler  in  the  linked  .EXE  file: 

rc  -t  program.exe 

If  Windows  3.0  is  running  in  real  mode,  it  will  not  load  such  a  program  for  execution. 
Instead,  Windows  will  display  a  message  box  indicating  that  the  program  requires  pro¬ 
tected  mode. 

Another  important  flag  is  -31.  This  indicates  that  your  program  requires  Windows  3.1. 
You  should  use  this  flag  when  taking  advantage  of  the  new  Windows  3.1  features.  By 
default,  the  resource  compiler  flags  the  .EXE  file  as  requiring  Windows  3.0. 

ICONS  AND  CURSORS 

Let’s  begin  by  looking  at  a  sample  program  that  uses  two  resources — an  icon  and  a  cursor. 
RESOURC1,  shown  in  Figure  8-1,  displays  a  customized  icon  when  the  program  is 
minimized  and  uses  a  customized  cursor  when  the  mouse  is  in  RESOURCES  client  area. 
RESOURC1  also  draws  its  icon  in  several  rows  and  columns  within  the  client  area. 

RESOURC1.MAK 

#---- . 

#  RES0URC1.MAK  make  file 

#  . 

resourcl.exe  :  resourcl.obj  resourcl.def  resourcl.res 

$(WINLINK)  resource  resourcl,  NUL,  $(WINLIB),  resourcl 
rc  -t  resourcl.res 

resourcl.obj  :  resourcl. c 
$ ( WI NCC )  resourcl. c 

resourcl.res  :  resourcl. rc  resourcl. ico  resourcl. cur 
$ ( WI NRC )  resourcl. rc 


RESOURC1.C 


/* . - . - . — . 

RES0URC1.C  --  Icon  and  Cursor  Demonstration  Program  No. 
(c)  Charles  Petzold,  1992 


*/ 


#include  <windows.h> 


Figure  8-1 .  The  RESOURC1  program,  including  an  icon  and  a  cursor 


(continued) 
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long  FAR  PASCAL  .export  WndProc  (HWND.  UINT,  UINT.  LONG)  ; 

char  szAppName  []  =  "Resourcl”  ; 

HANDLE  hlnst  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. IpszMenuName 
wndclass. IpszCl assName 


CS.HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (hlnstance,  szAppName)  ; 
LoadCursor  (hlnstance,  szAppName)  ; 
C0L0R.WIND0W  +  1  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hlnst  =  hlnstance  ; 


hwnd  =  CreateWindow  (szAppName,  "Icon  and  Cursor  Demo", 
WS_0V  ERLAP P EDW I NDOW , 

CW.USEDEFAULT,  CW.USEDEFAULT, 
CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 
{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


(continued) 
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{ 

static  HICON  hlcon  ; 

static  short  cxlcon,  cylcon,  cxClient,  cyClient  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 
short  x,  y  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hlcon  =  Loadlcon  (hlnst,  szAppName)  ; 
cxlcon  =  GetSystemMetrics  ( SM_CX I  CON )  ; 
cylcon  =  GetSystemMetrics  ( SM_CY I  CON )  ; 
return  0  ; 

case  WM_SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  H I WORD  (IParam)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

for  (y  =  cylcon  ;  y  <  cyClient  ;  y  +=  2  *  cylcon) 

for  (x  =  cxlcon  ;  x  <  cxClient  ;  x  +=  2  *  cxlcon) 
Drawlcon  (hdc,  x,  y,  hlcon)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


RESOURC1.RC 

/* . -  -  - - - 

RES0URC1 . RC  resource  script 
- - - */ 


resourcl  ICON  resourcl.ico 
resourcl  CURSOR  resourcl. cur 
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RESOURC1  .ICO 


RESOURC1.CUR 


RESOURC1.DEF 


RES0URC1.DEF  module  definition  file 


NAME  RES0URC1 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Icon  and  Cursor  Demo  Program  No. 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


(c)  Charles  Petzold,  1992' 


Both  the  icon  and  the  cursor  were  created  using  the  Image  Editor  program  supplied  with 
the  Windows  Software  Development  Kit.  They  are  shown  in  Figure  8-1  (at  the  top  of  this 
page)  against  a  light  gray  background.  Image  Editor  is  a  Windows  application,  and  it  re¬ 
quires  a  mouse.  Icons  are  saved  from  Image  Editor  with  a  .ICO  extension;  cursors  have  a 
.CUR  extension.  These  files  are  referred  to  in  the  RESOURC1.RC  resource  script. 
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The  Image  Editor 

The  Image  Editor  is  one  of  the  most  important  development  tools  in  the  Windows  Software 
Development  Kit.  (A  similar  tool  is  included  with  the  Borland  C++  compiler.)  The  program 
allows  you  to  create  bitmaps,  icons,  and  cursors  for  use  in  your  Windows  programs.  Icons 
and  cursors  are  both  variations  of  bitmaps,  so  it  will  be  helpful  to  examine  bitmaps  first. 

A  bitmap  is  an  array  of  bits  where  one  or  more  bits  corresponds  to  each  display  pixel. 
In  a  monochrome  bitmap,  one  bit  corresponds  to  one  pixel.  (In  the  simplest  case,  a  1  bit 
represents  white  and  a  0  bit  represents  black.  However,  bitmaps  are  often  used  in  logical 
operations  rather  than  merely  to  create  simple  drawings.)  In  a  color  bitmap,  multiple 
bits  correspond  to  each  pixel  to  represent  color.  The  Image  Editor  supports  the  creation 
of  monochrome  bitmaps  and  16-color  bitmaps.  In  a  16-color  bitmap,  4  bits  are  required 
for  each  pixel. 

A  bitmap  may  have  any  number  of  rows  and  columns.  (However,  the  bitmaps  you 
create  in  the  Image  Editor  are  limited  to  256  rows  and  256  columns.  You  can  create  larger 
bitmaps  in  PAINTBRUSH.)  Bitmaps  are  stored  in  files  with  a  .BMP  extension.  (I’ll  discuss 
the  format  of  the  bitmap  file  in  Chapter  13.) 

You  can  also  create  icons  and  cursors  in  the  Image  Editor.  Icons  and  cursors  are  very 
similar,  and  they  are  both  variations  of  bitmaps. 

Windows  displays  icons  and  cursors  on  the  screen  in  a  pixel  size  that  depends  on  the 
resolution  of  the  video  display.  This  ensures  that  the  icons  and  cursors  are  neither  too 
large  nor  too  small.  A  program  can  obtain  these  pixel  dimensions  using  the  GetSystem- 
Metrics  function  with  parameters  of  SM_CXICON,  SM-CYICON,  SM_CXCURSOR,  and 
SM-CYCURSOR.  On  most  video  displays,  the  dimensions  of  icons  and  cursors  are  identi¬ 
cal.  To  keep  it  simple  in  the  following  discussion,  I’ll  refer  only  to  icons,  but  keep  in  mind 
that  everything  I  say  applies  to  cursors  also. 

On  an  IBM  Color  Graphics  Adapter  (CGA),  the  width  of  an  icon  is  32  pixels  and  the 
height  is  16  pixels.  On  an  Enhanced  Graphics  Adapter  (EGA),  Video  Graphics  Array  (VGA), 
and  the  IBM  8514/A  video  adapter,  the  icons  are  32  pixels  wide  and  32  pixels  high.  On 
higher-resolution  adapters,  icons  could  be  displayed  as  64  pixels  by  64  pixels. 

Each  .ICO  file  can  contain  multiple  icon  images,  each  one  designed  for  the  particular 
resolutions  and  color  capabilities  of  the  various  video  adapters  on  which  your  Windows 
program  can  run.  The  Image  Editor  supports  three  different  image  formats.  When  you 
create  a  new  icon  file  (by  selecting  New  from  the  Image  Editor  File  menu),  you  select  one 
of  these  three  formats.  After  creating  an  icon  in  this  format,  you  can  then  select  another  of 
the  three  formats  from  the  New  Image  option  on  the  Edit  menu.  These  three  formats  are: 

■  32  pixels  by  16  pixels  with  2  colors  (monochrome) 

■  32  pixels  by  32  pixels  with  2  colors  (monochrome) 

■  32  pixels  by  32  pixels  with  16  colors 
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The  first  format  is  for  the  CGA,  and  the  second  is  for  other  video  adapters  (EGA,  VGA, 
and  8514/A)  running  in  a  monochrome  mode.  The  third  is  for  non-CGA  adapters  running 
in  color  modes.  The  EGA,  VGA,  and  8514/A  are  all  capable  of  16  colors. 

You  don’t  need  to  create  icon  images  in  all  three  formats.  When  a  program  contains 
an  icon  resource,  Windows  will  choose  the  format  that  most  closely  approximates  the  size 
and  color  capabilities  appropriate  to  the  video  adapter.  For  example,  if  you  create  only  32- 
by-32-pixel  icons  and  your  program  is  run  on  a  CGA,  Windows  will  display  the  icon  using 
every  other  row  of  pixels,  effectively  compressing  the  height  of  the  icon. 

If  you  create  only  a  32-by-32  icon  with  16  colors,  use  color  sparingly  because  the 
colors  can  be  approximated  only  with  gray  shades  (or  converted  to  black  or  white)  when 
running  with  a  monochrome  display.  If  you  create  both  monochrome  and  color  bitmaps, 
you  can  go  crazy  with  the  color.  All  the  icons  and  cursors  in  the  programs  in  this  chapter 
were  created  in  the  32-by-32  monochrome  format. 

When  you  create  an  icon  image  in  one  of  the  three  formats,  the  Image  Editor  actually 
stores  it  as  two  bitmaps — a  monochrome  bitmap  “mask”  and  a  monochrome  or  color  bit¬ 
map  image.  Icons  are  always  rectangular,  but  this  mask  allows  the  icon  to  appear  to  be 
nonrectangular.  That  is,  part  of  the  icon  allows  the  background  against  which  the  icon  is 
displayed  to  be  visible.  The  icon  can  also  contain  areas  that  invert  the  background  color. 

These  two  options  are  indicated  in  the  Image  Editor  by  buttons  labeled  “Screen”  and 
“Inverse.”  After  selecting  “Screen,”  anything  you  draw  in  the  icon  will  be  transparent,  and 
after  selecting  “Inverse,”  anything  you  draw  in  the  icon  will  invert  the  background.  The 
Image  Editor  displays  icons  against  a  light  gray  background,  so  anything  colored  with 
the  “Inverse”  option  will  appear  as  dark  gray. 

For  a  monochrome  icon,  the  following  table  shows  how  the  Image  Editor  constructs 
the  two  bitmaps  that  describe  the  icon: 


Color: 

Black 

White 

Screen 

Inverse  Screen 

Mask  Bitmap : 

0 

0 

1 

1 

Image  Bitmap: 

0 

1 

0 

1 

When  displaying  the  icon,  Windows  first  uses  a  bitwise  AND  operation  of  the  display  and 
the  first  bitmap.  The  display  pixels  corresponding  to  0  bits  from  the  first  bitmap  all  become 
0’s,  which  are  black.  The  display  pixels  corresponding  to  1  bit  remain  the  same.  This  is 
shown  in  the  following  logic  table: 


Display  Pixel 

Mask  Bit 

0  1 

0 

0  0 

1 

0  1 
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Next,  Windows  performs  a  bitwise  exclusive  OR  operation  of  the  image  bitmap  and 
the  display.  A  0  in  the  second  bitmap  leaves  the  display  pixel  the  same;  a  1  in  the  second 
bitmap  inverts  the  display  pixel.  Here’s  the  logic  table: 


Image  Bit 

Display  Pixel 

0  1 

0 

0 

1 

1 

1 

0 

Using  C  notation  for  the  operations,  the  display  is  altered  by  the  following  formula: 

Display  =  (Display  &  Mask)  A  Image 

For  a  16-color  icon,  the  mask  bitmap  is  still  monochrome  and  constructed  as  shown  above. 
The  image  bitmap  contains  4  bits  per  pixel  to  represent  16  colors.  All  four  bits  are  set  to  1 
for  areas  of  the  icon  that  invert  the  background. 

Earlier  I  said  that  when  talking  about  bitmaps,  0  does  not  necessarily  mean  black,  and 
1  does  not  necessarily  mean  white.  As  you  can  see  here,  it  depends  on  how  Windows  uses 
the  bitmaps.  (I’ll  discuss  this  more  in  Chapter  13.) 

In  RESOURC1,  I’ve  defined  the  window  class  to  make  the  background  of  the  client 
area  be  COLOR-WINDOW.  You  may  want  to  bring  up  the  Windows  Control  Panel  program 
and  change  the  window  color  to  see  how  the  icon  and  cursor  invert  colors. 

Getting  a  Handle  on  Icons 

A  resource  script  references  the  icon  file  with  a  statement  that  looks  like  this: 
my icon  ICON  iconfile.ico 

where  ICONFILE.ICO  is  the  name  of  the  icon  file.  This  statement  assigns  the  name 
“myicon”  to  the  icon.  In  your  C  program,  you  use  the  Loadlcon  function  to  obtain  a  handle 
to  the  icon.  Loadlcon  requires  two  parameters.  The  first  is  the  instance  handle  of  your  pro¬ 
gram,  generally  called  hlnstance  in  WinMain.  Windows  needs  this  handle  to  determine 
which  .EXE  file  contains  the  icon  resource.  The  second  parameter  is  the  icon  name  from 
the  resource  script,  in  the  form  of  a  pointer  to  a  null-terminated  string.  Loadlcon  returns  a 
value  of  type  HICON,  which  is  defined  in  WINDOWS.H. 

This  diagram  shows  the  relationship  between  the  icon  name  in  the  resource  script 
and  the  Loadlcon  statement  in  your  C  program: 

Resource  script:  myicon  ICON  iconfile.ico 

Program  source:  hlcon  =  Loadlcon  (hlnstance,  "myicon  ") ; 
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Don’t  worry  about  uppercase  and  lowercase  here.  The  resource  compiler  converts  the 
name  in  the  resource  script  file  to  uppercase  and  inserts  the  name  in  the  resource  table  of 
the  program’s  .EXE  file  header.  The  first  time  you  call  Loadlcon ,  Windows  converts  the 
string  in  the  second  parameter  to  uppercase  and  searches  the  resource  table  of  the  .EXE 
file  for  a  matching  name. 

You  can  speed  up  this  search  a  little  by  using  a  number  (an  unsigned  integer)  instead 
of  a  name.  This  number  is  called  an  ID  number  for  the  icon.  Here’s  how  it’s  done: 

Resource  script:  125  ICON  iconfile.ico 

Program  source:  hlcon  =  Loadlcon  (hlnstance,  MAKEINTRESOURCE( 125) ) ; 

MAKEINTRESOURCE  (“make  an  integer  into  a  resource  string”)  is  a  macro  defined  in 
WINDOWS.H  that  converts  a  number  into  a  far  pointer.  The  offset  address  is  set  to  the 
number,  and  the  segment  address  is  set  to  0.  Windows  knows  that  the  second  parameter  to 
Loadlcon  is  a  number  rather  than  a  pointer  to  a  character  string  because  the  segment  ad¬ 
dress  is  0. 

Sample  programs  presented  earlier  in  this  book  use  predefined  icons: 

Loadlcon  (NULL,  I D I_AP P L I C AT I  ON )  ; 

Windows  knows  that  this  is  a  predefined  icon  because  the  hlnstance  parameter  is  set 
to  NULL.  I DI -APPLICATION  happens  also  to  be  defined  in  WINDOWS.H  in  terms  of 
MAKEINTRESOURCE: 

^define  IDI_APPLICATION  MAKEI NTRESOURCE ( 32512 ) 

The  predefined  icons  and  cursors  are  part  of  the  display  driver  file. 

You  can  also  reference  the  icon  name  using  a  third  method  that  combines  the  string 
method  and  the  number  method: 

Resource  script:  125  ICON  iconfile.ico 

Program  source:  hlcon  =  Loadlcon  (hlnstance,  "#125") ; 

Windows  recognizes  the  initial  #  character  as  prefacing  a  number  in  ASCII  form. 

How  about  a  fourth  method?  This  one  uses  a  macro  definition  in  a  header  file  that  is 
included  (using  the  ^include  directive)  in  both  the  resource  script  and  your  program: 

Header  file:  # define  myicon  125 

Resource  script:  myicon  ICON  iconfile.ico 

Program  source:  hlcon  =  Loadlcon  (hlnstance,  MAKEINTRESOURCE  (myicon) ) ; 

Be  careful  when  you  use  this  method!  Although  case  does  not  matter  when  the  icon  name 
is  a  character  string,  case  does  make  a  difference  for  identifiers  that  are  generated  from 
# define  statements. 
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Using  ID  numbers  rather  than  names  for  icons  reduces  the  .EXE  file  size  and  speeds 
up  the  Loadlcon  call.  Moreover,  if  your  program  uses  many  icons,  you’ll  find  it  easier  to 
store  the  ID  numbers  in  an  array. 

Using  Icons  in  Your  Program 

Icons  have  only  a  couple  of  purposes.  Many  Windows  programs  use  an  icon  only  for 
displaying  the  minimized  program  in  the  icon  area.  This  is  accomplished  when  defining 
the  window  class: 

wndclass.hlcon  =  Loadlcon  (hlnstance,  "myicon")  ; 

If  you  later  want  to  change  the  program’s  icon,  you  can  do  so  using  SetClassWord. 
Let’s  assume  you  had  a  second  icon  in  your  resource  script: 

anothericon  ICON  i conf i 1 2 . i co 

You  can  substitute  this  icon  for  "myicon"  with  the  statement: 

SetClassWord  (hwnd.  GCW_H ICON,  Loadlcon  (hlnstance, "anothericon") )  ; 

If  you  save  the  icon  handle  from  a  Loadlcon  call,  you  can  also  draw  the  icon  on  the 
client  area  of  your  window: 

Drawlcon  (hdc,  x,  y,  hlcon)  ; 

Windows  itself  uses  the  Drawlcon  function  when  displaying  your  program’s  icon  in  the 
icon  area.  Windows  obtains  the  handle  to  the  icon  from  the  window  class  structure.  You 
can  obtain  the  handle  in  the  same  way: 

Drawlcon  (hdc,  x,  y,  GetClassWord  (hwnd,  GGW_H I  CON ) )  ; 

The  RESOURC1  sample  program  uses  the  same  icon  for  the  window  class  and  for  dis¬ 
playing  in  its  client  area.  In  the  resource  script  the  icon  is  given  the  same  name  as  the 
program: 

resourcl  ICON  resourcl.ico 

Because  the  character  string  "Resourcl"  is  stored  in  the  array  szAppName  and  is  already 
used  in  the  program  for  the  window  class  name,  the  Loadlcon  call  is  simply: 

Loadlcon  (hlnstance,  szAppName)  ; 

You’ll  notice  that  Loadlcon  is  called  twice  in  RESOURC1  for  the  same  icon,  once  when 
defining  the  window  class  in  WinMain  and  again  when  obtaining  a  handle  to  the  icon 
while  processing  the  WM_CREATE  message  in  WndProc.  Calling  Loadlcon  twice  presents 
no  problem:  Both  calls  return  the  same  handle.  Windows  actually  loads  the  icon  only  once 
from  the  .EXE  file  and  then  uses  it  for  all  instances  of  the  RESOURC1  program. 
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Using  Alternate  Cursors 

The  statements  that  you  use  to  specify  a  cursor  in  your  resource  script  and  to  obtain  a 
handle  to  a  cursor  in  your  program  are  very  similar  to  the  icon  statements  shown  above: 

Resource  script:  mycursor  CURSOR  cursfile.cur 

Program  source:  hCursor  =  LoadCursor  (hlnstance,  "mycursor") ; 

The  other  methods  shown  for  icons  (using  ID  numbers  and  MAKEINTRESOURCE)  work 
with  cursors  also.  WINDOWS.H  includes  a  typedef  dednidon  for  HCURSOR  that  you  can 
use  for  storing  the  cursor  handle.  (Both  HICON  and  HCURSOR  are  defined  as  HANDLE.) 

You  can  use  the  cursor  handle  obtained  from  LoadCursor  when  setting  the  hCursor 
member  of  the  window  class  structure: 

wndcl ass .hCursor  =  LoadCursor  (hlnstance.  "mycursor")  ; 

This  causes  the  mouse  cursor  to  be  displayed  as  your  customized  cursor  when  the  mouse  is 
within  the  client  area  of  your  window. 

If  you  use  child  windows,  you  may  want  the  cursor  to  appear  differently,  depending 
on  the  child  window  below  the  cursor.  If  your  program  defines  the  window  class  for  these 
child  windows,  you  can  use  different  cursors  for  each  class  by  appropriately  setting  the 
hCursorde\d  in  each  window  class.  And  if  you  use  predefined  child  window  controls,  you 
can  alter  the  hCursor  field  of  the  window  class  using: 

SetCl assWord  (hwndChild,  GCW.HCURSOR, 

LoadCursor  (hlnstance,  "chi  1 dcursor")  ; 

If  you  separate  your  client  area  into  smaller  logical  areas  without  using  child  win¬ 
dows,  you  can  use  SetCursor  to  change  the  mouse  cursor: 

SetCursor  (hCursor)  ; 

You  should  call  SetCursor  during  processing  of  the  WM_MOUSEMOVE  message.  Other¬ 
wise,  Windows  uses  the  cursor  specified  in  the  window  class  to  redraw  the  cursor  when 
it  is  moved. 

RESOURC1  uses  the  name  of  the  program  for  the  name  of  the  cursor: 
resourcl  CURSOR  resourcl.cur 

When  RESOURC1.C  defines  the  window  class,  the  following  szAppName  variable  is  used 
for  LoadCursor : 

wndclass. hCursor  =  LoadCursor  (hlnstance,  szAppName)  ; 


318 


Chapter  8:  Icons,  Cursors,  Bitmaps,  and  Strings 


RESOURCES  AND  MEMORY 

The  Loadlcon  and  LoadCursor  functions  certainly  sound  as  if  they  load  the  icon  or  cursor 
from  the  .EXE  file  into  memory.  They  do  not.  Windows  doesn’t  load  the  icon  or  cursor  until 
it  needs  the  object  for  drawing.  During  loading,  Windows  may  alter  the  object  to  fit  the 
dimensions  and  color  capabilities  of  the  display. 

Icons  and  cursors  (as  well  as  all  other  resources  except  bitmaps)  are  “owned”  by  the 
program.  Multiple  instances  of  the  same  program  share  the  same  cursors  and  icons  loaded 
into  memory.  When  the  last  instance  terminates,  Windows  frees  up  the  memory  occupied 
by  the  resource.  And  for  most  resources,  Windows  can  discard  the  resource  from  memory 
to  generate  free  space  and  then  load  it  back  into  memory  when  needed. 

You  can  override  some  of  these  characteristics,  however.  For  all  resources  except  the 
keyboard  accelerators  (covered  in  Chapter  9),  you  can  specify  “load”  and  “memory”  op¬ 
tions  in  the  resource  script  file.  These  options  are  similar  to  the  module  definition  file 
options  for  code  and  data  segments  discussed  in  Chapter  7.  In  the  resource  script,  the  load 
and  memory  options  follow  the  resource  type.  This  is  the  generalized  form  of  the  ICON 
statement  in  a  resource  script  file: 

iconID  ICON  [load-option]  [memory-option]  iconfile.ico 

The  load  option  can  be  either  PRELOAD  or  LOADONCALL.  A  resource  defined  as 
PRELOAD  will  be  loaded  into  memory  when  the  program  is  loaded.  LOADONCALL  means 
that  the  resource  will  not  be  loaded  until  Windows  needs  it.  LOADONCALL  is  the  default 
for  all  resources.  You  will  probably  want  to  use  PRELOAD  only  when  you  know  that  your 
program  will  need  the  resource  immediately  after  beginning  to  execute. 

The  memory  options  are  FIXED,  MOVEABLE,  and  DISCARDABLE.  DISCARDABLE 
resources  must  also  be  MOVEABLE.  For  the  resources  discussed  in  this  chapter,  the  icon, 
cursor,  and  character  string  resources  have  default  memory  options  of  MOVEABLE  and 
DISCARDABLE.  The  bitmap  and  user-defined  resources  are  MOVEABLE  only.  Why  the 
difference?  Icon,  cursor,  and  character  string  resources  are  read-only,  so  Windows  can 
safely  discard  them  from  memory.  Windows  allows  bitmaps  and  user-defined  resources 
to  be  modified  from  within  a  program — and  modified  resources  cannot  be  discarded. 

Bitmaps:  Pictures  in  Pixels 

We’ve  already  talked  about  the  use  of  bitmaps  in  icons  and  cursors.  Windows  also  includes 
a  resource  type  called  BITMAP. 

Bitmaps  are  used  for  two  major  purposes.  The  first  is  to  draw  pictures  on  the  display. 
For  instance,  the  Windows  display  driver  files  contain  lots  of  tiny  bitmaps  used  for  drawing 
the  arrows  in  scroll  bars,  the  check  marks  in  pull-down  menus,  the  system  menu  box,  the 
size  box,  check  boxes,  and  radio  buttons.  Programs  such  as  PAINTBRUSH  use  bitmaps  to 
display  a  graphics  menu. 
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The  second  major  use  of  bitmaps  is  to  create  brushes.  Brushes,  you’ll  recall,  are  pat¬ 
terns  of  pixels  that  Windows  uses  to  fill  an  area  of  the  display.  (Chapter  9  discusses  a  third 
and  less  common  use  of  bitmaps,  as  selection  items  in  menus.) 

Using  Bitmaps  and  Brushes 

The  RESOURC2  program,  shown  in  Figure  8-2,  is  an  upgraded  version  of  RESOURC1  that 
includes  a  monochrome  bitmap  resource  used  to  create  a  brush  for  the  background  of  the 
client  area.  The  bitmap  was  created  in  the  Image  Editor  with  dimensions  of  8  by  8,  which  is 
the  minimum  size  for  a  brush. 


RESOURC2.MAK 

# . . 

#  RES0URC2.MAK  make  file 

#  . - . 

resourc2.exe  :  resourc2.obj  resourc2.def  resourc2. res 

$(WINLINK)  resourc2,  resourc2,  NUL,  $(WINLIB),  resourc2 
rc  -t  resourc2.res 

resourc2.obj  :  resourc2.c 
$(WINCC)  resource2.c 

resourc2.res  :  resourc2.rc  resourc2.ico  resourc2.cur  resourc2.bmp 
$ ( WI NRC )  resourc2.rc 


RESOURC2.C 


/* 


RES0URC2.C  --  Icon  and  Cursor  Demonstration  Program  No.  2 
(c)  Charles  Petzold,  1992 


*/ 


#include  <windows.h> 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

char  szAppName[]  =  "Resourc2"  ; 

HANDLE  hlnst  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 


Figure  8-2.  The  RESOURC2 program,  including  an  icon,  a  cursor,  and  a  bitmap.  (continued) 
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{ 

HBITMAP  hBitmap  ; 
HBRUSH  hBrush  ; 
HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


hBitmap  =  LoadBitmap  (hlnstance,  szAppName)  ; 
hBrush  =  CreatePatternBrush  (hBitmap)  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbrBackg round 
wndclass. IpszMenuName 
wndclass. 1 pszCl assName 


CS.HREDRAW  !  CSJ/REDRAW  ; 
WndProc  ; 


hlnstance  ; 

Loadlcon  (hlnstance,  szAppName)  ; 
LoadCursor  (hlnstance,  szAppName)  ; 
hBrush  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hlnst  =  hlnstance  ; 


hwnd  =  CreateWindow  (szAppName,  "Icon  and  Cursor  Demo", 
WS_0 V  ERLAP  P  EDW I NDOW , 

CWJJSEDEFAULT,  CWJJSEDEFAULT. 
CW_USEDEFAULT,  CW_USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

DeleteObject  (hBrush)  ;  //  clean-up 

DeleteObject  (hBitmap)  ; 

return  msg.wParam  ; 

} 


(continued) 
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long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  1 Param) 

{ 

static  HICON  hlcon  ; 

static  short  cxlcon,  cylcon,  cxClient,  cyClient  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 
short  x,  y  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hlcon  =  Loadlcon  (hlnst,  szAppName)  ; 
cxlcon  =  GetSystemMetrics  (SM.CXICON)  ; 
cylcon  =  GetSystemMetrics  (SM.CYICON)  ; 
return  0  ; 

case  WM.SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HI WORD  (IParam)  ; 
return  0  ; 

case  WM.PAINT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

for  (y  =  cylcon  ;  y  <  cyClient  ;  y  +=  2  *  cylcon) 

for  (x  =  cxlcon  ;  x  <  cxClient  ;  x  +=  2  *  cxlcon) 
Drawlcon  (hdc,  x,  y,  hlcon)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


RESOURC2.RC 

/* . . 

RES0URC2.RC  resource  script 
-  .  .  . ---*/ 

resourc2  ICON  resourc2.ico 
resourc2  CURSOR  resourc2.cur 
resourc2  BITMAP  resourc2.bmp 
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RESOURC2.ICO 


RESOURC2.CUR 


RESOURC2.BMP 


RESOURC2.DEF 


RES0URC2.DEF  module  definition  file 


NAME  RES0URC2 


(continued) 
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DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Icon  and  Cursor  Demo  Program  No.  2  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


The  bitmap  resource  is  included  in  the  resource  script  in  the  same  format  as  the  icon 
and  cursor: 

resourc2  BITMAP  resourc2.bmp 

The  LoadBitmap  function  used  in  WinMain  is  similar  to  the  Loadlcon  and  Load- 
Cursor  calls.  It  returns  a  handle  to  a  bitmap: 

hBitmap  =  LoadBitmap  (hlnstance,  szAppName)  ; 

This  handle  is  then  used  to  create  a  pattern  brush.  The  brush  is  based  on  the  bitmap: 

hBrush  =  CreatePatternBrush  (hBitmap)  ; 

When  Windows  fills  an  area  of  the  display  with  this  brush,  the  bitmap  is  repeated  horizon¬ 
tally  and  vertically  every  eight  pixels.  We  want  to  use  this  brush  to  color  the  background  of 
the  client  area,  which  we  accomplish  when  defining  the  window  class: 

wndclass.hbrBackground  =  hBrush  ; 

The  major  difference  between  bitmaps  and  other  resources  is  of  practical  signifi¬ 
cance  and  can  be  simply  stated:  Bitmaps  are  GDI  objects.  They  are  not  shared  among  in¬ 
stances  of  your  program,  and  they  are  not  automatically  deleted  from  memory  when  your 
program  terminates.  Because  bitmaps  and  brushes  are  GDI  objects,  they  must  be  deleted 
before  the  program  terminates.  In  RESOURC2  this  is  done  at  the  end  of  WinMain : 

DeleteObject  (hBrush)  ; 

DeleteObject  (hBitmap)  ; 


CHARACTER  STRINGS 

Having  a  resource  for  character  strings  may  seem  odd  at  first.  Certainly  we  haven’t  had  any 
problem  using  regular  old  character  strings  defined  as  variables  right  in  our  source  code. 

Character  string  resources  are  primarily  for  easing  the  translation  of  your  program  to 
other  languages.  As  you’ll  discover  in  the  next  two  chapters,  menus  and  dialog  boxes  are 
also  part  of  the  resource  script.  If  you  use  character  string  resources  rather  than  put  strings 
directly  into  your  source  code,  then  all  text  that  your  program  uses  will  be  in  one  file — the 
resource  script.  If  the  text  in  this  resource  script  is  translated,  all  you  need  do  to  create  a 
foreign-language  version  of  your  program  is  relink  the  program  and  add  the  translated 
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resources  to  the  .EXE  file.  This  method  is  much  safer  than  messing  around  with  your  source 
code.  (Of  course,  you  could  also  choose  to  define  all  your  character  strings  as  macros  and 
store  them  in  a  header  file.  This  method  also  avoids  altering  source  code  during  language 
translations.) 

A  second  reason  for  using  character  string  resources  is  to  reduce  memory  space.  This 
reason  is  less  obvious — in  fact,  if  you  use  character  string  resources  inefficiently,  you 
might  not  reduce  memory  space  at  all.  We’ll  examine  this  problem  after  we  get  through 
the  basics. 

Using  Character  String  Resources 

The  character  string  resources  are  defined  in  your  resource  script  using  the  keyword 
STRINGTABLE: 

STRINGTABLE  [load  option]  [memory  option] 

{ 

nIDl,  "character  string  1" 
nID2,  "character  string  2" 

[other  string  definitions] 

} 

The  resource  script  can  contain  only  one  string  table.  LOADONCALL  is  the  default 
load  option;  MOVEABLE  and  DISCARDABLE  are  the  default  memory  options.  Each  string 
can  be  only  one  line  long  with  a  maximum  of  255  characters.  The  strings  cannot  contain 
any  C-style  control  characters  except  for  \t  (tab).  However,  the  strings  can  contain  octal 
constants: 


Tab 

\011 

Linefeed 

\  01 2 

Carriage  return 

\015 

These  control  characters  are  recognized  by  the  DrawText  and  MessageBox  functions. 

Your  program  can  use  the  LoadString  call  to  copy  a  string  resource  into  a  buffer  in  the 
program’s  data  segment: 

LoadString  (hlnstance,  nID,  IpszBuffer,  nMaxLength)  ; 

The  nID  parameter  refers  to  the  ID  number  that  precedes  each  string  in  the  resource  script; 
IpszBuffer  is  a  far  (or  long)  pointer  to  a  character  array  that  receives  the  character  string; 
and  nMaxLength  is  the  maximum  number  of  characters  to  transfer  into  the  IpszBuffer.  The 
string  ID  numbers  that  precede  each  string  are  generally  macro  identifiers  defined  in  a 
header  file.  Many  Windows  programmers  use  the  prefix  IDS-  to  denote  an  ID  number  for  a 
string.  Sometimes  a  filename  or  other  information  must  be  embedded  in  the  string  when 
the  string  is  displayed.  In  this  case  you  put  C  formatting  characters  in  the  string  and  use  it 
as  a  formatting  string  in  sprintf  or  wsprintf 
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Using  Strings  with  MessageBox 

Let’s  look  at  an  example  of  a  program  that  uses  three  character  strings  to  display  three  error 
messages  in  a  message  box.  A  header  file  that  we’ll  call  PROGRAM. H  defines  three  iden¬ 
tifiers  for  these  messages: 

//defi ne  I DS_F I LENOT FOUND  1 
//define  I DS_FI LETOOB I G  2 
//define  I DS_F I LEREADONLY  3 

The  resource  script  looks  like  this: 

//include  "program. h" 

[other  resource  script] 

STRINGTABLE 

{ 

I DS_F I LENOTFOUND,  "File  %s  not  found." 

IDS_FI LETOOBIG,  "File  %s  too  large  to  edit." 

IDS_FI LEREADONLY .  "File  %s  is  read-only." 


The  C  source  code  file  also  includes  this  header  file  and  defines  a  function  to  display 
a  message  box.  (I’m  assuming  that  szAppName  is  a  global  variable  that  contains  the 
program  name.) 

//include  "program. h" 

[other program  lines] 

OkMessage  ( HWND  hwnd,  WORD  wErrorNumber ,  char  *szFi 1 eName) 

{ 

char  szFormat  [40]  ; 
char  szBuffer  [60]  ; 


LoadString  (hlnst,  wErrorNumber ,  szFormat,  40)  ; 

sprintf  (szBuffer,  szFormat,  szFilename)  ; 

return  MessageBox  (hwnd,  szBuffer,  szAppName, 

MB_0K  I  MB_I CON EXC LAMAT ION)  ; 

} 

To  display  a  message  box  containing  the  “file  not  found’’  message,  the  program  calls: 
OkMessage  (hwnd,  IDS_FI LENOTFOUND ,  szFileName)  ; 


Character  Strings  and  Memory  Space 

Character  string  resources  usually  save  memory  space,  but  the  amount  of  space  saved 
depends  on  how  efficiently  they’re  used.  When  the  RC.EXE  resource  compiler  adds  strings 
to  the  .EXE  file,  the  strings  are  grouped  into  different  segments  depending  on  the  ID 
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numbers  of  the  strings.  Each  segment  contains  a  maximum  of  16  strings.  Strings  with  ID 
numbers  from  0  to  15  are  stored  in  one  segment,  from  16  to  31  are  in  another,  and  so  forth. 
Because  of  this  grouping  into  segments,  your  .EXE  file  will  be  shorter  if  you  use  consecu¬ 
tive  numbers  for  your  string  IDs. 

When  you  use  LoadString  to  copy  a  string  resource  into  memory,  however,  Windows 
loads  the  entire  segment  (containing  up  to  16  strings)  into  memory  as  a  resource  and  then 
also  copies  the  content  of  the  string  specified  in  the  LoadString  c all  to  a  buffer  in  your  pro¬ 
gram’s  data  segment.  So  when  string  resources  are  loaded  into  memory,  they  initially  oc¬ 
cupy  less  memory  if  you  do  not  use  consecutive  numbers  for  the  string  IDs.  Probably  the 
worst  way  to  use  string  resources  is  to  load  all  the  strings  into  separate  global  static  arrays 
during  program  initialization  in  WinMain.  If  you  do  that,  you  don’t  use  any  less  space  than 
if  you  had  included  the  strings  in  your  C  source  code.  In  fact,  you’ll  use  more  space, 
because  you’ll  set  the  size  of  these  arrays  somewhat  larger  than  the  actual  string  lengths. 
Here  are  some  general  rules  for  using  string  resources: 

■  Assign  string  ID  numbers  according  to  logical  groupings.  For  instance,  if 
five  strings  are  involved  in  one  section  of  your  program  and  six  strings  are 
involved  in  another  section,  you  might  use  ID  numbers  0  to  4  for  the  first 
group  of  strings  and  16  to  21  for  the  second  group. 

■  Whenever  possible,  load  the  strings  into  automatic  local  variables  within 
functions,  thus  freeing  up  the  space  when  the  function  is  exited.  (The 
OkMessage  function  shown  above  uses  this  approach.) 

■  Alternatively,  reuse  a  single  static  array  for  loading  strings. 

Here’s  an  example  of  the  last  approach.  Let’s  assume  that  your  program  never  re¬ 
quires  more  than  one  string  at  a  time.  You  can  define  a  function  that  loads  the  string  and 
returns  a  pointer  to  a  static  variable  containing  the  string: 

char  ^String  (WORD  wID) 

{ 

static  szBuffer  [256]  ; 

LoadString  (hlnst,  wID,  szBuffer,  255)  ; 
return  szBuffer  ; 

} 

If  you  want  to  use  DrawText  to  display  the  string  with  ID  number  45,  you  use  this 
statement: 

DrawText  (hdc,  String  (45),  -1,  &rect,  DT_LE FT )  ; 


327 


SECTION  III:  USING  RESOURCES 


Each  call  to  String  destroys  the  contents  of  the  static  buffer.  If  you  require  access  to 
(for  example)  three  strings  at  one  time,  you  can  modify  String  as  follows: 

char  *String  (WORD  wID,  short  n) 

{ 

static  szBuffer  [3] [256]  ; 

Loadstring  (hlnst,  wID,  szBuffer  [n],  255)  ; 
return  szBuffer  [n]  ; 

} 

When  you  call  String  now,  you  pass  an  ID  number  and  a  second  parameter  that  is  either 
0,  1,  or  2. 

USER-DEFINED  RESOURCES 

The  “user-defined  resource”  is  convenient  for  attaching  miscellaneous  data  to  your  .EXE 
file  and  obtaining  access  to  that  data  within  the  program.  The  data  can  be  in  any  format 
you  want.  The  Windows  functions  used  to  access  user-defined  resources  return  a  far 
pointer  to  the  data  when  Windows  loads  the  data  into  memory.  You  can  do  whatever  you 
want  with  that  data.  For  instance,  suppose  you  have  a  file  called  PROGHELP.TXT  that  con¬ 
tains  “help”  text  for  your  program.  This  file  needn’t  be  a  pure  ASCII  file:  It  can  also  contain 
binary  data,  such  as  pointers  that  would  aid  your  program  in  referencing  various  sections 
of  this  file.  Reference  this  file  with  a  statement  in  your  resource  script  that  looks  like  this: 

helptext  TEXT  proghelp.txt 

The  names  helptext  (the  name  of  the  resource)  and  TEXT  (the  type  of  the  resource)  in  this 
statement  can  be  any  names  you  want.  I’ve  capitalized  TEXT  simply  to  make  it  look  like  the 
ICON,  CURSOR,  and  BITMAP  statements.  What  we’re  doing  here  is  making  up  our  own 
type  of  resource,  called  TEXT. 

During  program  initialization  (for  example,  during  processing  of  the  WM -CREATE 
message),  you  can  obtain  a  handle  to  this  resource: 

hResource  =  LoadResource  (hlnstance, 

FindResource  (hlnstance,  "TEXT",  "helptext"))  ; 

The  variable  hResource  is  defined  with  type  HANDLE.  Despite  its  name,  LoadResource 
does  not  actually  load  the  resource  into  memory  just  yet.  The  LoadResource  and 
FindResource  functions  used  together  like  this  are  essentially  equivalent  to  the  Loadlcon 
and  LoadCursor  functions.  In  fact,  Loadlcon  and  LoadCursor  use  the  LoadResource  and 
FindResource  functions. 

You  can  use  numbers  rather  than  names  for  the  resource  name  and  resource  type. 
The  numbers  can  be  converted  to  far  pointers  in  the  FindResource  call  using  Makelnt- 
Resource.  The  numbers  used  for  the  resource  type  must  be  greater  than  255.  (Windows 
uses  numbers  between  1  and  9  when  calling  FindResource  for  existing  resource  types.) 
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When  you  need  access  to  the  text,  call  LockResource : 
lpHelpText  =  LockResource  (hResource)  ; 

LockResource  loads  the  resource  into  memory  (if  it  has  not  already  been  loaded),  locks  it 
using  the  GlobalLock function,  and  returns  a  far  pointer  to  it.  When  you’re  finished  access¬ 
ing  the  memory,  unlock  the  segment: 

Uni ockResource  (hResource)  ; 

This  allows  Windows  to  move  the  segment  in  memory  under  real  mode.  When  you’re  fin¬ 
ished  with  the  resource,  you  can  free  it  from  memory: 

FreeResource  (hResource)  ; 

The  resource  will  also  be  freed  when  your  program  terminates,  even  if  you  don’t  call 
FreeResource. 

Normally,  user-defined  resources  are  not  discardable  unless  you  include  the  DIS¬ 
CARDABLE  keyword  before  the  filename  in  the  resource  script.  But  if  you  use  the  pointer 
returned  from  LockResource  to  alter  as  well  as  read  the  data,  don’t  make  the  resource 
DISCARDABLE.  Note  also  that  the  same  resource  is  shared  among  all  instances  of  the  pro¬ 
gram.  If  each  instance  needs  its  own  copy  of  the  resource,  you  should  make  the  resource 
discardable,  use  LockResource  to  obtain  a  pointer  to  the  resource,  use  GlobalAlloc  to  obtain 
a  global  memory  block  of  the  same  size,  use  GlobalLock  to  lock  that  block,  and  then  copy 
the  contents  of  the  resource  into  the  global  memory  block. 

Let’s  look  at  a  sample  program  that  uses  three  resources — an  icon,  a  string  table,  and 
a  user-defined  resource.  The  POEPOEM  program,  shown  in  Figure  8-3,  displays  the  text  of 
Edgar  Allan  Poe’s  “Annabel  Lee”  in  its  client  area.  The  user-defined  resource  is  the  file 
POEPOEM.ASC,  which  contains  the  text  of  the  poem.  The  text  file  is  terminated  with  a 
backslash  (\). 

POEPOEM. MAK 

# 

#  POEPOEM. MAK  make  file 

#  . 

poepoem.exe  :  poepoem.obj  poepoem.def  poepoem.res 

$ ( WI NLI NK)  poepoem,  poepoem,  NUL,  $ (WINLIB) ,  poepoem 
rc  -t  poepoem.res 

poepoem.obj  :  poepoem. c  poepoem. h 
$ ( WI NCC )  poepoem. c 

poepoem.res  :  poepoem. rc  poepoem. ico  poepoem. asc  poepoem. h 
$ ( WI NRC )  poepoem. rc 

Figure  8-3.  The  POEPOEM  program,  including  an  icon  and  a  user-defined  resource. 
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POEPOEM.C 


/* . . . - . — . 

POEPOEM.C  --  Demonstrates  User-Defined  Resource 
(c)  Charles  Petzold,  1992 

.  */ 


//include  <windows.h> 

//include  "poepoem.h" 

#define  min(a.b)  (((a)  <  (b))  ?  (a)  :  (b) ) 

//define  max(a,b)  (((a)  >  ( b) )  ?  (a)  :  (b)) 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

char  szAppName  [10]  ; 
char  szCaption  [35]  ; 

HANDLE  hlnst  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

LoadString  (hlnstance,  IDS.APPNAME,  szAppName,  sizeof  szAppName)  ; 
Loadstring  (hlnstance,  IDS.CAPTION,  szCaption,  sizeof  szCaption)  ; 


wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass . 1 pszMenuName 
wndclass. 1 pszCl assName 


=  CS.HREDRAW  !  CS.VREDRAW  ; 
=  WndProc  ; 


=  hlnstance  ; 

=  Loadlcon  (hlnstance,  szAppName)  ; 
=  LoadCursor  (NULL,  IDC.ARR0W)  ; 

=  GetStockObject  (WHITE.BRUSH)  ; 

=  NULL  ; 

=  szAppName  ; 


RegisterClass  (&wndclass)  ; 

} 

else 

{ 

GetlnstanceData  (hPrevInstance,  (PBYTE)  szAppName,  sizeof  szAppName)  ; 
GetlnstanceData  (hPrevInstance,  (PBYTE)  szCaption,  sizeof  szCaption)  ; 
} 


(continued) 
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hlnst  =  hlnstance  ; 

hwnd  =  CreateWindow  (szAppName,  szCaption, 

WS_OVERLAPP EDWIN DOW  !  WS.CLIPCHILDREN, 
CW_USEDEFAULT,  CWJJSEDEFAULT, 

CWJJSEDEFAULT,  CW_USEDE FAULT . 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HANDLE  hResource  ; 
static  HWND  hScroll  ; 

static  short  nPosition,  cxChar,  cyChar,  cyClient,  nNumLines,  xScroll  ; 
char  szPoemRes  [15]  ; 

char  far  *lpText  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

RECT  rect  ; 

TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 

cxChar  =  tm. tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm.tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 

xScroll  =  GetSystemMetrics  (SM.CXVSCROLL)  ; 

hScroll  =  CreateWindow  ("scrollbar”,  NULL, 

WS.CHILD  !  WS.VISIBLE  !  SBSJ/ERT, 

0,  0,  0 ,  0, 

hwnd,  1,  hlnst,  NULL)  ; 


(continued) 
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Loadstring  (hlnst,  IDS_POEMRES,  sz PoemRes,  sizeof  szPoemRes)  ; 
hResource  =  LoadResource  (hlnst, 

FindResource  (hlnst,  szPoemRes,  "TEXT"))  ; 

lpText  =  LockResource  (hResource)  ; 

nNumLines  =  0  ; 

while  (*lpText  !=  'W  &&  *lpText  !=  *\0' ) 

{ 

if  (*lpText  ==  '\n') 
nNumLines  ++  ; 

lpText  =  AnsiNext  (lpText)  ; 

} 

*lpText  =  ' \0 '  ; 

GlobalUnlock  (hResource)  ; 

SetScrol 1  Range  (hScroll,  SB_CTL,  0,  nNumLines,  FALSE)  ; 
SetScrol 1 Pos  (hScroll,  SB_CTL,  0,  FALSE)  ; 
return  0  ; 

case  WM_SIZE  : 

MoveWindow  (hScroll,  LOWORD  (IParam)  -  xScroll,  0, 
xScroll,  cyClient  =  HIWORD  (IParam),  TRUE)  ; 

SetFocus  (hwnd)  ; 
return  0  ; 

case  WM_SETFOCUS  : 

SetFocus  (hScroll)  ; 
return  0  ; 

case  WM.VSCROLL  : 
switch  (wParam) 

{ 

case  SB_T0P  : 

nPosition  =  0  ; 
break  ; 

case  SB_B0TT0M  : 

nPosition  =  nNumLines  ; 
break  ; 

case  SB_LI NEUP  : 

nPosition  -=  1  ; 
break  ; 

case  SB_LI N EDOWN  : 
nPosition  +=  1  ; 
break  ; 

case  SB.PAGEUP  : 

nPosition  -=  cyClient  /  cyChar  ; 
break  ; 


(continued) 
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case  SB.PAGEDOWN  : 

nPosition  +=  cyClient  /  cyChar  ; 
break  ; 

case  S B_T HUMBPOSITION  : 

nPosition  =  LOWORD  (lParam)  ; 
break  ; 

} 

nPosition  =  max  (0,  min  (nPosition,  nNumLines))  ; 

if  (nPosition  !=  GetScrollPos  (hScroll,  SB_CTL) ) 

{ 

SetScrollPos  (hScroll.  SB_CTL,  nPosition,  TRUE)  ; 
Inval idateRect  (hwnd,  NULL,  TRUE)  ; 

} 

return  0  ; 
case  WM.PAINT: 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

lpText  =  LockResource  (hResource)  ; 

GetClientRect  (hwnd,  &rect)  ; 

rect.left  +=  cxChar  ; 

rect.top  +=  cyChar  *  (l  -  nPosition)  ; 

DrawText  (hdc,  lpText,  -1,  &rect,  DT.EXTERNALLEADING)  ; 

GlobalUnlock  (hResource)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM.DESTROY  : 

FreeResource  (hResource)  ; 

PostQui tMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  lParam)  ; 

} 


POEPOEM.RC 

/* . - 

POEPOEM.RC  resource  script 
. - . */ 


#include  "poepoem.h" 


(continued) 
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poepoem  ICON  poepoem.ico 
Annabel  Lee  TEXT  poepoem. asc 


STRINGTABLE 

< 

IDS_APPNAME,  "poepoem" 

I DS_CAPT ION ,  """Annabel  Lee""  by  Edgar  Allen  Poe" 
IDS_POEMRES ,  "Annabel Lee" 

} 


POEPOEM.ICO 


POEPOEM. H 


/* . . 

POEPOEM. H  header  file 

*/ 


//define  IDS.APPNAME  0 
//define  IDS_CAPTION  1 
//define  IDS.POEMRES  2 


POEPOEM.ASC 

It  was  many  and  many  a  year  ago, 

In  a  kingdom  by  the  sea, 

That  a  maiden  there  lived  whom  you  may  know 
By  the  name  of  Annabel  Lee; 

And  this  maiden  she  lived  with  no  other  thought 
Than  to  love  and  be  loved  by  me. 


(continued) 
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I  was  a  child  and  she  was  a  child 
In  this  kingdom  by  the  sea, 

But  we  loved  with  a  love  that  was  more  than  love  -- 
I  and  my  Annabel  Lee  -- 
With  a  love  that  the  winged  seraphs  of  Heaven 
Coveted  her  and  me. 

And  this  was  the  reason  that,  long  ago, 

In  this  kingdom  by  the  sea, 

A  wind  blew  out  of  a  cloud,  chilling 
My  beautiful  Annabel  Lee; 

So  that  her  highborn  kinsmen  came 
And  bore  her  away  from  me, 

To  shut  her  up  in  a  sepulchre 
In  this  kingdom  by  the  sea. 

The  angels,  not  half  so  happy  in  Heaven, 

Went  envying  her  and  me  -- 
Yes!  that  was  the  reason  (as  all  men  know, 

In  this  kingdom  by  the  sea) 

That  the  wind  came  out  of  the  cloud  by  night. 
Chilling  and  killing  my  Annabel  Lee. 

But  our  love  it  was  stronger  by  far  than  the  love 
Of  those  who  were  older  than  we  -- 
Of  many  far  wiser  than  we  -- 
And  neither  the  angels  in  Heaven  above 
Nor  the  demons  down  under  the  sea 
Can  ever  dissever  my  soul  from  the  soul 
Of  the  beautiful  Annabel  Lee: 

For  the  moon  never  beams,  without  bringing  me  dreams 
Of  the  beautiful  Annabel  Lee; 

And  the  stars  never  rise,  but  I  feel  the  bright  eyes 
Of  the  beautiful  Annabel  Lee: 

And  so,  all  the  night-tide,  I  lie  down  by  the  side 
Of  my  darling  --  my  darling  --  my  life  and  my  bride, 
In  her  sepulchre  there  by  the  sea  -- 
In  her  tomb  by  the  sounding  sea. 


[May  1849] 


POEPOEM.DEF 


POEPOEM. DEF  module  definition  file 


(continued) 
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NAME  POEPOEM 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Demo  of  User-Defined  Resource  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


In  the  POEPOEM. RC  resource  script,  the  user-defined  resource  is  given  the  type  TEXT  and 
the  name  AnnabelLee : 

Annabel  Lee  TEXT  poepoem.asc 

During  WM-CREATE  processing  in  WndProc,  a  handle  to  the  resource  is  obtained 
using  FindResource  and  LoadResource.  The  resource  is  locked  using  LockResource,  and  a 
small  routine  replaces  the  backslash  (\)  at  the  end  of  the  file  with  a  0.  (This  is  for  the 
benefit  of  the  DrawText  function  used  later.)  In  most  cases  it’s  not  a  good  idea  to  write  on  a 
user-defined  resource  directly,  because  the  same  resource  is  shared  among  all  instances  of 
the  program.  However,  later  instances  of  POEPOEM  will  not  encounter  problems  with  the 
change  we’ve  made.  The  resource  is  then  unlocked  using  GlobalUnlock. 

The  resource  is  also  locked  and  unlocked  during  processing  of  WM_PAINT  to  write 
the  text  to  the  display  using  DrawText.  Note  the  use  of  a  child  window  scroll  bar  control 
rather  than  a  window  scroll  bar.  The  child  window  scroll  bar  control  has  an  automatic  key¬ 
board  interface,  so  no  WM-KEYDOWN  processing  is  required  in  POEPOEM. 

POEPOEM  also  uses  three  character  strings,  the  IDs  of  which  are  defined  in  the 
POEPOEM. H  header  file.  For  the  first  instance  of  the  program,  the  IDS_APPNAME  and 
IDS -CAPTION  strings  are  loaded  into  global  static  variables  using  LoadString 

Loadstring  (hlnstance,  IDS_APPNAME,  szAppName,  sizeof  szAppName)  ; 

LoadString  (hlnstance,  IDS_CAPTION,  szCaption,  sizeof  szCaption)  ; 

However,  for  subsequent  instances  of  POEPOEM,  the  strings  are  copied  from  the  previous 
instance: 

GetlnstanceData  (hPrevInstance,  szAppName,  sizeof  szAppName)  ; 

GetlnstanceData  (hPrevInstance,  szCaption,  sizeof  szCaption)  ; 

GetlnstanceData  is  faster  than  LoadString  if  the  string  resource  has  been  discarded  from 
memory.  The  pointers  ( szAppName  and  szCaption)  are  near  pointers  to  static  global  vari¬ 
ables.  Windows  uses  these  pointers  in  combination  with  the  data  segment  address  of  the 
previous  instance  and  the  data  segment  address  of  the  current  instance  to  copy  the  con¬ 
tents  of  the  variables. 
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Now  that  we’ve  defined  all  the  character  strings  used  in  POEPOEM  as  resources, 
we’ve  made  it  easier  for  translators  to  convert  the  program  to  a  foreign-language  version. 
Of  course,  they’d  also  have  to  translate  the  text  of  “Annabel  Lee” — which  would,  I 
suspect,  be  a  somewhat  more  difficult  task. 
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Menus  and 
Accelerators 


Menus  are  an  important  part  of  the  consistent  user  interface  that  Windows  programs  offer. 
Adding  a  menu  to  your  program  is  a  relatively  easy  part  of  Windows  programming:  You 
simply  define  the  structure  of  the  menu  in  your  resource  script  and  assign  a  unique  ID 
number  to  each  menu  item.  You  specify  the  name  of  the  menu  in  the  window  class 
structure.  When  the  user  chooses  a  menu  item,  Windows  sends  your  program  a 
WM_COMMAND  message  containing  that  ID.  But  we  won’t  stop  with  that  simple  example. 
One  of  the  more  interesting  things  you  can  do  with  menus  is  display  bitmaps  in  the  menu 
rather  than  character  strings,  so  we’ll  take  a  detailed  look  at  how  that  is  done. 

This  chapter  also  covers  “keyboard  accelerators.”  These  are  key  combinations  that 
are  used  primarily  to  duplicate  menu  functions. 

MENUS 

A  window’s  menu  bar  is  displayed  immediately  below  the  caption  bar.  This  menu  bar  is 
sometimes  called  a  program’s  “main  menu”  or  the  “top-level  menu.”  Items  listed  in  the 
top-level  menu  almost  always  invoke  a  drop-down  menu,  which  is  called  either  a  “popup 
menu”  or  a  “submenu.”  Beginning  with  Windows  3,  you  can  define  multiple  nestings  of 
popups:  that  is,  an  item  on  a  popup  menu  can  invoke  another  popup  menu.  Sometimes 
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items  in  popup  menus  invoke  a  dialog  box  for  more  information.  (Dialog  boxes  are  covered 
in  Chapter  10.)  Most  parent  windows  have,  to  the  far  left  of  the  caption  bar,  a  box  containing 
a  single  line.  This  box  invokes  the  system  menu,  which  is  really  another  popup  menu. 

Menu  items  in  popups  can  be  “checked,”  which  means  that  Windows  draws  a  small 
check  mark  to  the  left  of  the  menu  text.  The  use  of  check  marks  lets  the  user  choose  differ¬ 
ent  program  options  from  the  menu.  These  options  can  be  mutually  exclusive,  but  they 
don’t  have  to  be.  Top-level  menu  items  cannot  be  checked. 

Menu  items  in  the  top-level  menu  or  in  popup  menus  can  be  “enabled,”  “disabled,” 
or  “grayed.”  The  words  “active”  and  “inactive”  are  sometimes  used  synonymously  with 
“enabled”  and  “disabled.”  Menu  items  flagged  as  enabled  or  disabled  look  the  same  to  the 
user,  but  a  grayed  menu  item  is  displayed  in  gray  text. 

From  the  perspective  of  the  user,  enabled,  disabled,  and  grayed  menu  items  can  all 
be  “selected”  (highlighted).  That  is,  the  user  can  click  the  mouse  on  a  disabled  menu  item, 
or  move  the  reverse-video  cursor  bar  to  a  disabled  menu  item,  or  trigger  the  menu  item 
using  the  item’s  key  letter.  However,  from  the  perspective  of  your  program,  enabled, 
disabled,  and  grayed  menu  items  function  differently.  Windows  sends  your  program  a 
WM_COMMAND  message  only  for  enabled  menu  items.  You  use  disabled  and  grayed 
menu  items  for  options  that  are  not  currently  valid.  If  you  want  to  let  the  user  know  the 
option  is  not  valid,  make  it  grayed. 

Menu  Structure 

When  you  create  or  change  menus  in  a  program,  it’s  useful  to  think  of  the  top-level  menu 
and  each  popup  menu  as  being  separate  menus.  The  top-level  menu  has  a  menu  handle, 
each  popup  menu  within  a  top-level  menu  has  its  own  menu  handle,  and  the  system  menu 
(which  is  also  a  popup)  has  a  menu  handle. 

Each  item  in  a  menu  is  defined  by  three  characteristics.  The  first  characteristic  is 
what  appears  in  the  menu.  This  is  either  a  text  string  or  a  bitmap.  The  second  characteristic 
is  either  an  ID  number  that  Windows  sends  to  your  program  in  a  WM_COMMAND  mes¬ 
sage  or  a  popup  menu  that  Windows  displays  when  the  user  chooses  that  menu  item.  The 
third  characteristic  describes  the  attribute  of  the  menu  item,  including  whether  the  item  is 
disabled,  grayed,  or  checked. 

The  Menu  Template 

You  can  create  a  menu  in  three  different  ways.  The  most  common  (and  the  easiest)  is  to 
define  the  menu  in  your  resource  script  in  the  form  of  a  menu  template.  This  example 
shows  all  the  different  options  you  can  use  in  this  template: 
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MyMenu  MENU  [load  option]  [memory  option] 

{ 

MENUITEM  "&0ne",  1 

POPUP  "&Two" 


{ 

MENUITEM  "&Ten", 
MENUITEM  "&Eleven", 
MENUITEM  SEPARATOR 
MENUITEM  "T&welve", 
MENUITEM  "T&hi rteen" , 
MENUITEM  ’^Fourteen", 
MENUITEM  "F&ifteen", 
MENUITEM  "&Sixteen", 
POPUP  "Se&venteen" 


10,  CHECKED 
11 

12,  INACTIVE 
13 

14,  MENUBREAK 

15, 

16,  MENUBARBREAK 


{ 


MENUITEM  "&Twenty" ,  20 
MENUITEM  "T&wenty-One" ,  21 
MENUITEM  "Tw&enty-Two" ,  22 
} 


MENUITEM  "Ei &ghteen" ,  18,  GRAYED 

} 

MENUITEM  "Th&ree" ,  3 

MENUITEM  "&Four",  4,  INACTIVE 
MENUITEM  "Fi&ve" ,  5 

MENUITEM  "Si&x",  6,  MENUBREAK 

MENUITEM  "&Seven" ,  7, 

MENUITEM  "&Ei ght" ,  8,  GRAYED 

MENUITEM  "\a&Hel p" ,  9,  HELP 

} 


This  particular  menu  template  defines  a  top-level  menu  that  displays  the  labels 
“One”  through  “Eight”  and  “Help,”  as  shown  in  Figure  9-1  on  the  following  page.  Only  the 
second  item  invokes  a  popup  menu.  The  popup  menu  displays  the  labels  “Ten”  through 
“Eighteen,”’  as  shown  in  Figure  9-2  on  the  following  page.  The  little  arrow  to  the  right  of 
the  “Seventeen”  option  indicates  that  it  invokes  yet  another  popup  menu. 

MyMenu  is  the  name  of  the  menu.  This  name  performs  the  same  function  as  the 
names  of  icon,  cursor,  and  bitmap  resources  discussed  in  Chapter  8.  As  with  other  re¬ 
sources,  the  load  option  on  the  MENU  statement  can  be  either  PRELOAD  (in  which  case 
Windows  loads  the  resource  into  memory  when  the  program  is  executed)  or  LOADON- 
CALL  (in  which  case  Windows  loads  the  resource  into  memory  only  when  it  is  needed). 
The  default  is  LOADONCALL.  The  memory  options  are  FIXED,  MOVEABLE,  and  DIS¬ 
CARDABLE.  The  default  is  MOVEABLE  and  DISCARDABLE.  Discardable  menus  must  also 
be  moveable.  Although  we’ll  change  menus  in  some  of  the  programs  shown  later,  don’t 
worry  that  the  menu  resource  is  discardable.  Windows  makes  a  copy  of  the  menu  for  your 
program  to  use  and  change. 
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The  top-level  menu  is  enclosed  in  left  and  right  brackets.  (You  can  use  BEGIN  and 
END  statements  instead  if  you  wish.)  The  two  types  of  statements  allowed  within  these 
brackets  are: 

MENUITEM  "text",  wID  [.options] 

and: 


POPUP  "text"  [.options] 

The  text  displayed  for  each  menu  must  be  enclosed  in  double  quotation  marks.  An  amper¬ 
sand  (&)  causes  the  character  that  follows  it  to  be  underlined  when  Windows  displays  the 
menu.  This  is  also  the  character  Windows  searches  for  when  you  select  a  menu  item  using 
the  Alt  key.  If  you  don’t  include  an  ampersand  in  the  text,  no  underline  will  appear,  and 
Windows  will  use  instead  the  first  letter  of  the  text  for  Alt-key  searches. 

The  options  on  the  MENUITEM  and  POPUP  statements  that  appear  in  the  top-level 
menu  list  are  as  follows: 

■  GRAYED — The  menu  item  is  inactive,  and  it  does  not  generate  a 
WM_COMMAND  message.  The  text  is  grayed. 

■  INACTIVE — The  menu  item  is  inactive,  and  it  does  not  generate  a 
WM-COMMAND  message.  The  text  is  displayed  normally. 

■  MENUBREAK — This  item  and  the  following  items  appear  on  a  new  line 
of  the  menu. 

■  HELP — When  used  in  combination  with  \a  before  the  text,  this  item  is 
right-justified. 

Options  can  be  combined  using  the  C  bitwise  OR  symbol  (  !  ),  but  GRAYED  and  INACTIVE 
cannot  be  used  together.  MENUBREAK  is  uncommon  in  a  top-level  menu,  because  Win¬ 
dows  automatically  separates  a  top-level  menu  into  multiple  lines  if  the  window  is  too 
narrow  to  fit  the  entire  menu. 

Following  a  POPUP  statement  in  the  main  menu,  the  left  and  right  brackets  (or  the 
BEGIN  and  END  keywords)  block  off  a  list  of  items  in  the  popup.  The  following  statements 
are  allowed  in  a  popup  definition: 

MENUITEM  "text" ,  wID  [.options] 

and: 


MENUITEM  SEPARATOR 

and: 

POPUP  "text"  [.options] 

MENUITEM  SEPARATOR  draws  a  horizontal  line  in  the  popup  menu.  This  line  is  often 
used  to  separate  groups  of  related  options. 
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For  items  in  popup  menus,  you  can  use  the  columnar  tab  character  \t  in  the  character 
string.  Text  following  the  \t  is  placed  in  a  new  column  spaced  far  enough  to  the  right  to 
accommodate  the  longest  text  string  in  the  first  column  of  the  popup.  We’ll  see  how  this 
works  when  discussing  keyboard  accelerators  toward  the  end  of  this  chapter.  A  \a  right- 
justifies  the  text  that  follows  it.  The  options  for  MENUITEM  in  a  popup  are  as  follows: 

■  CHECKED — A  check  mark  appears  to  the  left  of  the  text. 

■  GRAYED — The  menu  item  is  inactive,  and  it  does  not  generate  a 
WM_COMMAND  message.  The  text  is  grayed. 

■  INACTIVE — The  menu  item  is  inactive,  and  it  does  not  generate  a 
WM_COMMAND  message.  The  text  is  displayed  normally. 

■  MENUBREAK — This  item  and  the  following  items  appear  in  a  new 
column  of  the  menu. 

■  MENUBARBREAK — This  item  and  the  following  items  appear  in  a  new 
column  of  the  menu.  A  vertical  line  separates  the  columns. 

GRAYED  and  INACTIVE  cannot  be  used  together.  MENUBREAK  and  MENUBARBREAK 
cannot  be  used  together.  You  should  use  either  MENUBREAK  or  MENUBARBREAK  when 
the  number  of  items  in  a  popup  are  “taller”  than  can  be  displayed  in  a  single  column. 

The  wID  values  in  the  MENUITEM  statements  are  the  numbers  that  Windows  sends 
to  the  window  procedure  in  menu  messages.  The  wID  values  should  be  unique  within  a 
menu.  Instead  of  using  numbers,  you’ll  probably  want  to  use  identifiers  defined  in  a  header 
file.  By  convention,  these  identifiers  begin  with  the  letters  IDM  (“ID  for  a  menu”). 

Referencing  the  Menu  in  Your  Program 

Most  Windows  applications  have  only  one  menu  in  the  resource  script.  The  program 
makes  reference  to  this  menu  in  the  definition  of  the  window  class: 

wndcl ass . 1 pszMenuName  =  "My Menu"  ; 

Programmers  often  use  the  name  of  the  program  as  the  name  of  the  menu  so  that  the  same 
character  string  can  also  be  used  for  the  window  class,  the  name  of  the  program’s  icon,  and 
the  name  of  the  menu.  However,  you  can  also  use  a  number  (or  a  macro  identifier)  for  the 
menu  rather  than  a  name.  The  resource  script  would  look  like  this: 

45  MENU 

{ 

[menu  definition] 

} 
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In  this  case,  the  assignment  statement  for  the  IpszMenuName  field  of  the  window  class 
structure  can  be  either: 

wndclass. IpszMenuName  =  MAKEINTRESOURCE  (45)  ; 


or: 


wndclass. IpszMenuName  =  "#45"  ; 

Although  specifying  the  menu  in  the  window  class  is  the  most  common  way  to  refer¬ 
ence  a  menu  resource,  you  have  alternatives.  A  Windows  application  can  load  a  menu 
resource  into  memory  with  the  LoadMenu  function,  which  is  similar  to  the  Loadlcon  and 
LoadCursor  functions  described  in  Chapter  8.  If  you  use  a  name  for  the  menu  in  the 
resource  script,  LoadMenu  returns  a  handle  to  the  menu: 

hMenu  =  LoadMenu  (hlnstance,  "MyMenu")  ; 

If  you  use  a  number,  the  LoadMenu  call  takes  either  this  form: 

hMenu  =  LoadMenu  (hlnstance,  MAKEINTRESOURCE  (45))  ; 

or  this  form: 

hMenu  =  LoadMenu  (hlnstance,  "#45")  ; 

You  can  then  specify  this  menu  handle  as  the  ninth  parameter  to  CreateWindow : 

hwnd  =  CreateWindow  ("MyClass",  "Window  Caption", 

WS_OVERLAPP EDWIN DOW, 

CW_USEDEFAULT,CW_USEDE FAULT, 

CW_USEDEFAULT,CW_USEDE FAULT, 

NULL, 

hMenu, 

hlnstance, 

NULL)  ; 

In  this  case,  the  menu  specified  in  the  CreateWindow  call  overrides  any  menu  specified  in 
the  window  class.  You  can  think  of  the  menu  in  the  window  class  as  being  a  default  menu 
for  the  windows  based  on  the  window  class  if  the  ninth  parameter  to  CreateWindow  is 
NULL.  Therefore,  you  can  use  different  menus  for  several  windows  based  on  the  same  win¬ 
dow  class. 

You  can  also  have  a  NULL  menu  in  the  window  class  and  a  NULL  menu  in  the 
CreateWindow  call  and  assign  a  menu  to  a  window  after  the  window  has  been  created: 

SetMenu  (hwnd,  hMenu)  ; 

This  form  lets  you  dynamically  change  a  window’s  menu.  We’ll  see  an  example  of  this  in 
the  NOPOPUPS  program  shown  later  in  this  chapter. 

Any  menu  that  is  attached  to  a  window  is  destroyed  when  the  window  is  destroyed. 
Any  menus  not  attached  to  a  window  should  be  explicitly  destroyed  by  calls  to 
DestroyMenu  before  the  program  terminates. 
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Menus  and  Messages 

Windows  usually  sends  a  window  procedure  several  different  messages  when  the  user 
selects  a  menu  item.  In  most  cases  your  program  can  ignore  many  of  these  messages  and 
simply  pass  them  to  DefWindowProc.  Let’s  take  a  look  at  them  anyway. 

The  first  message  your  program  receives  when  the  user  selects  a  menu  item  with  the 
keyboard  or  mouse  is  a  WM_SYSCOMMAND  message.  The  values  of  wParam  and  IParam 
are  shown  below: 


wParam 

IParam 

Mouse: 

F09x 

0 

Keyboard 

FlOx 

0 

The  WINDOWS.H  identifier  SC_MOUSEMENU  is  equal  to  F090H;  SC-KEYMENU  is  F100H, 
but  the  last  digit  in  wParam  (indicated  by  an  x  in  the  table  above)  can  be  anything.  Use: 

(wParam  &  0xFFF0) 


if  you  need  to  check  this  value.  Most  programs  pass  these  messages  to  DefWindowProc . 

The  second  message  your  program  receives  is  a  WM_INITMENU  message  with  the 
following  parameters: 


wParam 

LOWORD  (IParam) 

HI  WORD  (IParam) 

Handle  to  main  menu 

0 

0 

The  value  of  wParam  is  the  handle  to  your  main  menu  even  if  the  user  is  selecting  an  item 
from  the  system  menu.  Windows  programs  generally  ignore  the  WM_INITMENU  mes¬ 
sage.  Although  the  message  exists  to  give  you  the  opportunity  to  change  the  menu  before 
an  item  is  chosen,  I  suspect  any  changes  to  the  top-level  menu  at  this  time  would  be  very 
disconcerting  to  the  user. 

The  next  message  your  program  receives  is  WM_MENUSELECT.  A  program  can 
receive  many  WM_MENUSELECT  messages  as  the  user  moves  the  cursor  or  mouse  among 
the  menu  items.  The  parameters  that  accompany  WM_SELECT  are  as  follows: 


wParam 

LOWORD  (IParam) 

HIWORD  (IParam) 

Selected  item:  Menu  ID 
or  popup  menu  handle 

Selection  flags 

Handle  to  menu  containing 
selected  item 

WM_MENUSELECT  is  a  menu-tracking  message.  The  value  of  wParam  tells  you  what  item 
of  the  menu  is  currently  selected  (highlighted).  The  “selection  flags”  in  the  low  word 
of  IParam  can  be  a  combination  of  the  following:  MF-GRAYED,  MF-DISABLED, 
MF_CHECKED,  MF_BITMAP,  MF_POPUP,  MF_HELP,  MF_SYSMENU,  and  MF.MOUSE- 
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SELECT.  You  may  want  to  use  WM_MENUSELECT  if  you  need  to  change  something  in 
the  client  area  of  your  window  based  on  the  movement  of  the  highlight  among  the  menu 
items.  Most  programs  pass  this  message  to  DefWindowProc. 

When  Windows  is  ready  to  display  a  popup  menu,  it  sends  the  window  procedure  a 
WM_INITMENUPOPUP  message  with  the  following  parameters: 


wParam 

LOWORD  (IParam) 

HI  WORD  (IParam) 

Popup  menu  handle 

Popup  index 

1  for  system  menu,  0  otherwise 

This  message  is  important  if  you  need  to  enable  or  disable  items  in  a  popup  menu  before  it 
is  displayed.  For  instance,  suppose  your  program  can  copy  text  from  the  clipboard  using 
the  Paste  command  on  a  popup  menu.  When  you  receive  a  WM_INITMENUPOPUP  mes¬ 
sage  for  that  popup,  you  should  determine  if  the  clipboard  has  text  in  it.  If  it  doesn’t,  you 
should  gray  the  Paste  menu  item.  We’ll  see  an  example  of  this  in  the  revised  POPPAD  pro¬ 
gram  shown  toward  the  end  of  this  chapter. 

The  most  important  menu  message  is  WM_COMMAND.  This  message  indicates  that 
the  user  has  chosen  an  enabled  menu  item  from  your  window’s  menu.  You’ll  recall  from 
Chapter  6  that  WM .COMMAND  messages  also  result  from  child  window  controls.  If  you 
happen  to  use  the  same  ID  codes  for  menus  and  child  window  controls,  you  can  differenti¬ 
ate  between  them  by  the  low  word  of  IParam,  which  will  be  0  for  a  menu  item: 


wParam 

LOWORD  (IParam) 

HIWORD  (IParam) 

Menu:  Menu  ID 

Control  Control  ID 

0 

Child  window  handle 

0 

Notification  code 

The  WM.SYSCOMMAND  message  is  similar  to  the  WM.COMMAND  message  ex¬ 
cept  that  WM.SYSCOMMAND  signals  that  the  user  has  chosen  an  enabled  menu  item  from 
the  system  menu: 

wParam 

LOWORD  (IParam) 

HIWORD  (IParam) 

System  menu :  Menu  ID 

0 

0 

The  menu  ID  indicates  which  item  on  the  system  menu  has  been  chosen.  For  the  pre¬ 
defined  system  menu  items,  the  bottom  four  bits  should  be  masked  out.  The  resultant  value 
will  be  one  of  the  following:  SC.SIZE,  SC.MOVE,  SC.MINIMIZE,  SC.MAXIMIZE, 
SC.NEXTWINDOW,  SC.PREVWINDOW,  SC.CLOSE,  SC.VSCROLL,  SC.HSCROLL,  SC- 
.ARRANGE,  SC.RESTORE,  and  SC.TASKLIST.  In  addition,  wParam  can  be  SC.MOUSE- 
MENU  or  SC.KEYMENU,  as  indicated  earlier. 

If  you  add  menu  items  to  the  system  menu,  wParam  will  be  the  menu  ID  that  you 
define.  To  avoid  conflicts  with  the  predefined  menu  IDs,  use  values  below  F000H.  It  is 
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important  that  you  pass  normal  WM_SYSCOMMAND  messages  to  DefWindowProc.  If 
you  do  not,  you’ll  effectively  disable  the  normal  system  menu  commands. 

The  final  message  we’ll  discuss  is  WM_MENUCHAR,  which  isn’t  really  a  menu  mes¬ 
sage  at  all.  Windows  sends  this  message  to  your  window  procedure  in  one  of  two  circum¬ 
stances:  if  the  user  presses  Alt  and  a  character  key  that  does  not  correspond  to  a  menu  item, 
or,  when  a  popup  is  displayed,  if  the  user  presses  a  character  key  that  does  not  correspond 
to  an  item  in  the  popup.  The  parameters  that  accompany  the  WM_MENUCHAR  message 
are  as  follows: 


wParam 

LOWORD  (IParam) 

HI  WORD  (IParam) 

ASCII  code 

Selection  code 

Handle  to  menu 

The  selection  code  is: 


■  0 — No  popup  is  displayed. 

■  MF_POPUP — Popup  is  displayed. 

■  MF_SYSMENU — System  menu  popup  is  displayed. 

Windows  programs  usually  pass  this  message  to  DefWindowProc ,  which  normally  returns 
a  0  to  Windows,  which  causes  Windows  to  beep.  We’ll  see  a  use  for  the  WM_MENUCHAR 
message  in  the  GRAFMENU  program  shown  later  in  this  chapter. 

A  Sample  Program 

Let's  look  at  a  simple  example.  The  MENUDEMO  program,  shown  in  Figure  9-3,  has  five 
items  in  the  main  menu — File,  Edit,  Background,  Timer,  and  Help.  Each  of  these  items  has 
a  popup.  MENUDEMO  does  the  simplest  and  most  common  type  of  menu  processing, 
which  involves  trapping  WM_COMMAND  messages  and  checking  the  value  of  wParam. 

MENUDEMO. MAK 

# 

#  MENUDEMO. MAK  make  file 

# 

menudemo.exe  :  menudemo.obj  menudemo.def  menudemo. res 

$ (WINLINK)  menudemo,  menudemo,  NUL,  $(WINLIB),  menudemo 
rc  -t  menudemo. res 

menudemo.obj  :  menudemo. c  menudemo. h 
$ ( WI NCC )  menudemo. c 

menudemo. res  :  menudemo. rc  menudemo. h 
$ ( W I NRC )  menudemo. rc 

Figure  9-3.  The  MENUDEMO  program. 
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MENUDEMO.C 

/* . 

MENUDEMO.C  --  Menu  Demonstration 

(c)  Charles  Petzold,  1992 
. */ 

#include  <windows.h> 

/^include  "menudemo.h" 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 
char  szAppName  []  =  "MenuDemo"  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 
wndclass. cbClsExtra  =  0  ; 
wndclass. cbWndExtra  =  0  ; 
wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  Loadlcon  (NULL,  I DI_APPLICATION )  ; 

wndclass. hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass. hbrBackground  =  GetStockObject  (WHITE.BRUSH)  ; 
wndclass. IpszMenuName  =  szAppName  ; 
wndclass.lpszClassName  =  szAppName  ; 

RegisterClass  Uwndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Menu  Demonstration", 

WS.OVERLAPP EDWIN DOW, 

CW.USEDEFAULT,  CW.USEDEFAULT, 

CW.USEDEFAULT,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

(continued) 
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while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&rnsg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  ( HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  int  wColorlD  [5]  =  {  WHITE.BRUSH,  LTGRAY.BRUSH,  GRAY.BRUSH, 

DKGRAY.BRUSH,  BLACK.BRUSH  }  ; 
static  WORD  wSelection  =  IDM.WHITE  ; 

HMENU  hMenu  ; 

switch  (message) 

{ 

case  WM.COMMAND  : 

hMenu  =  GetMenu  (hwnd)  ; 

switch  (wParam) 

{ 

case  IDM.NEW  : 
case  IDM.OPEN  : 
case  IDM.SAVE  : 
case  IDM.SAVEAS  : 

MessageBeep  (0)  ; 
return  0  ; 

case  IDM.EXIT  : 

SendMessage  (hwnd,  WM.CLOSE,  0,  0L)  ; 
return  0  ; 

case  IDMJJNDO  : 
case  IDM.CUT  : 
case  IDM.COPY  : 
case  IDM.PASTE  : 
case  IDM.DEL  : 

MessageBeep  (0)  ; 
return  0  ; 

case  IDM.WHITE  : 
case  IDM.LTGRAY  : 
case  IDM.GRAY  : 
case  IDM.DKGRAY  : 
case  I DM_B LACK  : 


//  Note:  The  logic  below 
//  assumes  that  IDM.WHITE 

//  through  IDM.BLACK  are 

//  consecutive  numbers  in 

//  the  order  shown  here. 


(continued) 
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CheckMenuItem  (hMenu,  wSelection,  MFJJNCHECKED)  ; 
wSelection  =  wParam  ; 

CheckMenuItem  (hMenu,  wSelection,  MF_CHECKED)  ; 

SetCl assWord  (hwnd,  GCW.HBRBACKGROUND, 

GetStockObject  (wColorlD  [wParam  -  I DM_WH ITE] ) )  ; 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

case  IDM_START  : 

if  (SetTimer  (hwnd,  1,  1000,  NULL)) 

{ 

EnableMenuItem  (hMenu,  IDM_$TART,  MF.GRAYED)  ; 
EnableMenuItem  (hMenu,  IDM.STOP,  MF_ENAB LED )  ; 

} 

return  0  ; 

case  IDM_ST0P  : 

Kill  Timer  (hwnd,  1)  ; 

EnableMenuItem  (hMenu,  IDM_START,  MF_ENAB LED )  ; 
EnableMenuItem  (hMenu,  IDM_ST0P,  MF.GRAYED)  ; 
return  0  ; 

case  I DM_H E LP  : 

MessageBox  (hwnd,  "Help  not  yet  implemented!", 

szAppName,  MB_I CON EXC LAMAT ION  !  MB_0K)  ; 

return  0  ; 
case  IDM_AB0UT  : 

MessageBox  (hwnd,  "Menu  Demonstration  Program.", 

szAppName,  MB_I CON  I N  FORMATION  !  MB_0K)  ; 

return  0  ; 

} 

break  ; 

case  WM_TI MER  : 

MessageBeep  (0)  ; 
return  0  ; 

case  WM.DESTROY  : 

PostQui tMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
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MENUDEMO.RC 


/* 

MENUDEMO.RC  resource  script 
. */ 


#include  "menudemo.h" 


MenuDemo  MENU 

{ 

POPUP  "&File" 

{ 

MENUITEM  "&New", 

MENUITEM  "&0pen. . .", 

MENUITEM  "&Save", 

MENUITEM  "Save  &As...", 
MENUITEM  SEPARATOR 
MENUITEM  "E&xit", 

} 

POPUP  "&Edit" 

{ 

MENUITEM  "&Undo" , 

MENUITEM  SEPARATOR 
MENUITEM  "Cu&t" , 

MENUITEM  "&Copy", 

MENUITEM  "&Paste", 

MENUITEM  "De&lete", 

} 

POPUP  "&Background" 

{ 

MENUITEM  "&White", 

MENUITEM  "&Lt  Gray", 

MENUITEM  "&Gray" , 

MENUITEM  "&Dk  Gray", 

MENUITEM  "&B1 ack", 

} 

POPUP  "&Timer" 

{ 

MENUITEM  "&Start" 

MENUITEM  "S&top" 

} 

POPUP  "&Hel p" 

{ 

MENUITEM  "&Help. . 

MENUITEM  "&About  MenuDemo...", 

} 

} 


I DM_NEW 
IDM_0PEN 
IDM_SAVE 
I DM_SAV  EAS 

IDM_EXIT 


IDM.UND0 

IDM_CUT 

IDM_C0PY 

IDM_PASTE 

IDM_DEL 


IDM_WHITE, 
IDM.LTGRAY 
IDM_GRAY 
IDM_DKGRAY 
I DM_B  LACK 


IDM.START 
IDM_ST0P , 


IDM_HELP 

IDM.AB0UT 


CHECKED 


GRAYED 
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MENUDEMO.H 

/* . - . - . 

MENUDEMO.H  header  file 


//define  I DM_NEW  1 
//define  IDM_0PEN  2 
//define  IDM_SAVE  3 
//define  IDM.SAVEAS  4 
//define  IDM_EXIT  5 

//define  IDM_UND0  10 
//define  IDM.CUT  11 
//define  IDM_C0PY  12 
//define  IDM_PASTE  13 
//define  IDMJ3EL  14 

//define  IDM_WHITE  20 
//define  IDMJJGRAY  21 
//define  IDM_GRAY  22 
//define  IDM_DKGRAY  23 
//define  IDM_BLACK  24 

//define  IDM_START  30 
//define  IDM_ST0P  31 

//define  IDM_HELP  40 
//define  IDM_AB0UT  41 


MENUDEMO.DEF 


MENUDEMO.DEF  module  definition  file 


NAME  MENUDEMO 


DESCRIPTION  'Menu  Demonstration  Program  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 
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Identifiers  for  all  menu  IDs  are  defined  in  MENUDEMO.H.  This  file  must  be  specified 
(using  a  # include  statement)  in  both  the  resource  script  file  and  the  C  source  code  file.  The 
identifiers  begin  with  IDM.  The  ID  numbers  defined  for  the  menu  items  need  not  be  con¬ 
secutive.  However,  if  you  process  these  IDs  in  your  program  using  switch  and  case  state¬ 
ments,  keep  in  mind  that  the  C  compiler  can  best  optimize  this  code  using  jump  tables  if 
you  use  consecutive  menu  ID  numbers. 

The  MENUDEMO  program  simply  beeps  when  it  receives  a  WM_COMMAND  mes¬ 
sage  for  most  items  in  the  File  and  Edit  popups.  The  Background  popup  lists  five  stock 
brushes  that  MENUDEMO  can  use  to  color  the  background.  In  the  MENUDEMO.RC 
resource  script  the  White  menu  item  (with  a  menu  ID  of  IDM_WHITE)  is  flagged  as 
CHECKED,  which  places  a  check  mark  next  to  the  item.  In  MENUDEMO. C,  the  value  of 
wSelection  is  initially  set  to  IDM-WHITE. 

The  five  brushes  on  the  Background  popup  menu  are  mutually  exclusive.  When 
MENUDEMO. C  receives  a  WM_COMMAND  message  where  wParam  is  one  of  these  five 
items  on  the  Background  popup,  it  must  remove  the  check  mark  from  the  previously 
chosen  background  color  and  add  a  check  mark  to  the  new  background  color.  To  do  this,  it 
first  gets  a  handle  to  its  menu: 

hMenu  =  GetMenu  (hwnd)  ; 

The  CheckMenuItem  function  is  used  to  uncheck  the  currently  checked  item: 

CheckMenuItem  (hMenu,  wSelection,  M F_UNCH ECKED )  ; 

The  wSelection  value  is  set  to  the  value  of  wParam ,  and  the  new  background  color  is 
checked: 

wSelection  =  wParam  ; 

CheckMenuItem  (hMenu,  wSelection,  MF_CH EC KED )  ; 

The  background  color  in  the  window  class  is  then  replaced  with  the  new  background 
color,  and  the  window  client  area  is  invalidated.  Windows  erases  the  window  using  the 
new  background  color. 

The  Timer  popup  lists  two  options — Start  and  Stop.  Initially,  the  Stop  option  is 
grayed  (as  indicated  in  the  menu  definition  for  the  resource  script).  When  you  choose  the 
Start  option,  MENUDEMO  tries  to  start  a  timer  and,  if  successful,  grays  the  Start  option  and 
makes  the  Stop  option  active: 

Enabl eMenuItem  (hMenu,  IDM.START,  MF.GRAYED)  ; 

Enabl eMenuItem  (hMenu.  IDM.STOP,  M F_EN AB LED )  ; 

On  receipt  of  a  WM_COMMAND  message  with  wParam  equal  to  IDM_STOP, 
MENUDEMO  kills  the  timer,  activates  the  Start  option,  and  grays  the  Stop  option: 

EnableMenuItem  (hMenu,  IDM.START,  MF.ENABLED)  ; 

Enabl eMenuItem  (hMenu,  IDM.STOP,  MF.GRAYED)  ; 
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Notice  that  it’s  impossible  for  MENUDEMO  to  receive  a  WM -COMMAND  message 
with  wParam  equal  to  IDM-START  while  the  timer  is  going.  Similarly,  it’s  impossible  to 
receive  a  WM-COMMAND  with  wParam  equal  to  IDM-STOP  while  the  timer  is  not  going. 

When  MENUDEMO  receives  a  WM -COMMAND  message  with  the  wParam  parame¬ 
ter  equal  to  IDM-ABOUT  or  IDM-HELP,  it  displays  a  message  box.  (In  Chapter  10,  we’ll 
change  this  to  a  dialog  box.) 

When  MENUDEMO  receives  a  WM -COMMAND  message  with  wParam  equal  to 
IDM-EXIT,  it  sends  itself  a  WM-CLOSE  message.  This  is  the  same  message  that  DefWin- 
dowProc  sends  the  window  procedure  when  it  receives  a  WM-SYSCOMMAND  message 
with  wParam  equal  to  SC-CLOSE.  We’ll  examine  this  more  in  the  POPPAD2  program 
shown  toward  the  end  of  this  chapter. 

Menu  Etiquette 

The  format  of  the  File  and  Edit  popups  in  MENUDEMO  is  quite  similar  to  the  formats  in 
other  Windows  programs.  One  of  the  objectives  of  Windows  is  to  provide  a  user  with  a 
recognizable  interface  that  does  not  require  relearning  basic  concepts  for  each  program.  It 
certainly  helps  if  the  File  and  Edit  menus  look  the  same  in  every  Windows  program  and  use 
the  same  letters  for  selection  in  combination  with  the  Alt  key. 

Beyond  the  File  and  Edit  popups,  the  menus  of  most  Windows  programs  will  be  dif¬ 
ferent.  When  designing  a  menu  you  should  look  at  existing  Windows  programs  and  aim  for 
some  consistency.  Of  course,  if  you  think  these  other  programs  are  wrong  and  you  know 
the  right  way  to  do  it,  nobody’s  going  to  stop  you.  Also  keep  in  mind  that  revising  a  menu 
usually  requires  revising  only  the  resource  script  and  not  your  program  code.  You  can 
move  menu  items  around  at  a  later  time  without  many  problems. 

At  the  beginning  of  this  chapter,  I  showed  you  a  menu  with  nine  top-level  items  but 
with  only  one  popup  that  is  invoked  from  the  top-level  menu.  This  menu  is  certainly  atypi¬ 
cal.  Most  often,  each  top-level  item  has  a  popup,  even  if  the  popup  has  only  one  option. 
Top-level  items  without  popups  can  be  too  easily  chosen  by  mistake. 

Defining  a  Menu  the  Hard  Way 

Defining  a  menu  in  a  program’s  resource  script  is  usually  the  easiest  way  to  add  a  menu  in 
your  window,  but  it’s  not  the  only  way.  You  can  dispense  with  the  resource  script  and 
create  a  menu  entirely  within  your  program  using  two  functions  called  CreateMenu  and 
AppendMenu.  After  you  finish  defining  the  menu,  you  can  pass  the  menu  handle  to 
CreateWindow  or  use  SetMenu  to  set  the  window’s  menu. 

Here’s  how  it’s  done.  CreateMenu  simply  returns  a  handle  to  a  new  menu: 

hMenu  =  CreateMenu  0  ; 
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The  menu  is  initially  empty.  AppendMenu  inserts  items  into  the  menu.  You  must  obtain  a 
different  menu  handle  for  the  top-level  menu  item  and  for  each  popup.  The  popups  are 
constructed  separately;  the  popup  menu  handles  are  then  inserted  into  the  top-level  menu. 
The  code  shown  in  Figure  9-4  creates  a  menu  in  this  fashion;  in  fact,  it  is  the  same  menu  as 
in  the  MENUDEMO  program. 

hMenu  =  CreateMenu  0  ; 
hMenuPopup  =  CreateMenu  0  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM_NEW,  "&NewM)  ; 

AppendMenu  (hMenuPopup,  MF.STRING,  IDM_0PEN,  "&0pen. . .")  ; 

AppendMenu  (hMenuPopup,  MF_$TRING,  IDM_SAVE,  "&Save")  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM.SAVEAS,  "Save  &As...")  ; 

AppendMenu  (hMenuPopup,  MF_SEPARATOR,  0,  NULL)  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM_EXIT,  "E&xit")  ; 

AppendMenu  (hMenu,  MF_P0PUP,  hMenuPopup,  ,f&Fi  1  e,f)  ; 

hMenuPopup  =  CreateMenu  0  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM_UND0,  "&Undo")  ; 

AppendMenu  (hMenuPopup,  M  F_S  E  PA  RAT  0  R ,  0,  NULL)  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM_CUT,  "Cu&t")  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM.COPY,  "&Copy")  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM.PASTE,  "&Paste")  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM_DEL,  "De&lete")  ; 

AppendMenu  (hMenu,  MF_P0PUP,  hMenuPopup,  "&Edit")  ; 

hMenuPopup  =  CreateMenu  0  ; 

AppendMenu  (hMenuPopup,  MF_STRING  !  MF_CHECKED,  I DM_WH I TE ,  "&White")  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM_LTGRAY,  M&Lt  Gray")  ; 

AppendMenu  (hMenuPopup,  MF.STRING,  IDM.GRAY,  "&Gray")  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  IDM.DKGRAY,  "&Dk  Gray")  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  I DM_B LACK ,  "&Black")  ; 

AppendMenu  (hMenu,  MF_P0PUP,  hMenuPopup,  "&Background")  ; 

hMenuPopup  =  CreateMenu  0  ; 

AppendMenu  (hMenuPopup,  MF.STRING,  IDM.START,  "&Start")  ; 

AppendMenu  (hMenuPopup,  MF.STRING  !  MF_GRAYED,  IDM_ST0P,  "S&top")  ; 

Figure  9-4.  C  code  that  creates  the  same  menu  as  used  in  the  MENUDEMO  (continued) 

program  but  without  requiring  a  resource  script  file. 
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AppendMenu  (hMenu,  MF_P0PUP,  hMenuPopup,  ”&Timer")  ; 
hMenuPopup  =  CreateMenu  0  ; 


AppendMenu  (hMenuPopup,  MF.STRING,  IDM_HELP,  "&Help")  ; 

AppendMenu  (hMenuPopup,  MF_STRING,  I DM__AB0UT ,  "&About  MenuDemo. . ; 


AppendMenu  (hMenu,  MF.POPUP,  hMenuPopup,  "&Help")  ; 


I  think  you’ll  agree  that  the  resource  script  menu  template  is  easier  and  clearer.  I’m  not  rec¬ 
ommending  that  you  define  a  menu  in  this  way  only  showing  that  it  can  be  done.  Certainly 
you  could  cut  down  on  the  code  size  substantially  by  using  some  arrays  of  structures  con¬ 
taining  all  the  menu  item  character  strings,  IDs,  and  flags.  But  if  you  do  that,  you  might  as 
well  take  advantage  of  the  third  method  Windows  provides  for  defining  a  menu. 

A  Third  Approach  to  Defining  Menus 

The  LoadMenuIndirect  function  accepts  a  pointer  to  a  structure  of  type  MENUITEM- 
TEMPLATE  and  returns  a  handle  to  a  menu.  This  function  is  used  within  Windows  to  con¬ 
struct  a  menu  after  loading  the  normal  menu  template  from  a  resource  script.  If  you’re 
brave,  you  can  try  using  it  yourself. 

Be  forewarned,  however:  The  MENUITEMTEMPLATE  structure  has  a  field  defined 
as  LPSTR  that  is  set  to  a  far  pointer  to  a  character  string,  a  handle  to  a  popup,  or  a  handle  to 
a  bitmap.  But  if  you  need  to  run  in  real  mode,  you  can’t  simply  define  a  MENUITEMTEMP¬ 
LATE  structure  in  your  program  and  initialize  the  field  to  a  character  string.  During  com¬ 
pilation,  the  pointer  to  the  character  string  is  converted  to  a  far  pointer.  This  violates  one  of 
the  most  important  rules  discussed  in  Chapter  7:  Don’t  store  far  pointers  to  your  data  seg¬ 
ment.  Instead,  immediately  before  calling  LoadMenuIndirect ,  you  use  a  series  of  assign¬ 
ment  statements  to  set  this  field  to  the  character  string  pointers.  Between  these  assignment 
statements  and  the  LoadMenuIndirect  call,  you  can’t  make  any  Windows  calls  (such  as 
GetMessage')  that  can  result  in  your  data  segment  being  moved. 

Floating  Popup  Menus 

Beginning  with  Windows  3,  you  can  make  use  of  menus  without  having  a  top-level  menu 
bar.  You  can  instead  cause  a  popup  menu  to  appear  on  top  of  any  part  of  the  screen.  One 
approach  is  to  invoke  this  popup  menu  in  response  to  a  click  of  the  right  mouse  button. 
However,  menu  items  must  still  be  selected  with  the  left  mouse  button.  The  POPMENU 
program  in  Figure  9-5  (beginning  on  the  following  page)  shows  how  this  is  done. 
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POPMENU.MAK 

# . - . 

#  POPMENU.MAK  make  file 

#  . 

popmenu.exe  :  popmenu.obj  popmenu.def  popmenu.res 

$(WINLINK)  popmenu,  popmenu,  NUL,  $(WINLIB),  popmenu 
rc  -t  popmenu.res 

popmenu.obj  :  popmenu. c  popmenu. h 
$ ( W I NCC )  popmenu. c 

popmenu.res  :  popmenu. rc  popmenu. h 
$ ( WI NRC )  popmenu. rc 


POPMENU.C 

/* . 

POPMENU.C  --  Popup  Menu  Demonstration 
(c)  Charles  Petzold,  1992 
. */ 


#include  <windows.h> 

#include  "popmenu. h" 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

char  szAppName  []  =  "PopMenu"  ; 

HANDLE  hlnst  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. IpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 

Figure  9-5.  The  POPMENU  program. 


=  CS.HREDRAW  !  CS.VREDRAW  ; 
=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 


( continued ) 
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wndclass.hlcon  =  Loadlcon  (NULL,  IDI_APPLICATION)  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
wndclass.lpszMenuName  =  NULL  ; 
wndclass.lpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hlnst  =  hlnstance  ; 

hwnd  =  CreateWindow  (szAppName,  "Popup  Menu  Demonstration", 

WS_OVERLAPP EDWIN DOW , 

CWJJSEDEFAULT,  CW_USEDEFAULT, 

CW_US EDE FAU LT ,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  ^export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HMENU  hMenu  ; 

static  int  wColorlD  [5]  =  {  WHITE_BRUSH,  LTGRAY_BRUSH,  GRAY.BRUSH, 

DKGRAY.BRUSH,  BLACK_BRUSH  }  ; 
static  WORD  wSelection  =  I DM_WH I TE  ; 

POINT  point  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hMenu  =  LoadMenu  (hlnst,  szAppName)  ; 
hMenu  =  GetSubMenu  (hMenu,  0)  ; 
return  0  ; 

case  WM_RBUTT0ND0WN  : 

point  =  MAKEPOINT  (IParam)  ; 

Cl ientToScreen  (hwnd,  &point)  ; 

TrackPopupMenu  (hMenu,  0,  point. x,  point. y,  0,  hwnd,  NULL)  ; 
return  0  ; 


(continued) 
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case  WM.COMMAND  : 
switch  (wParam) 
{ 


case 

IDM_NEW  : 

case 

IDM_OPEN  : 

case 

IDM.SAVE  : 

case 

IDM.SAVEAS  : 

case 

I DM_UN DO  : 

case 

IDM.CUT  : 

case 

IDM_COPY  : 

case 

IDM_PASTE  : 

case 

IDM.DEL  : 
MessageBeep  (0)  ; 
return  0  ; 

case 

I DM_WH ITE  : 

// 

Note:  The  logic  below 

case 

IDM_LTGRAY  : 

// 

assumes  that  I DM_WH ITE 

case 

IDM_GRAY  : 

// 

through  IDM_BLACK  are 

case 

IDM_DKGRAY  : 

// 

consecutive  numbers  in 

case 

I DM_B LACK  : 

// 

the  order  shown  here. 

CheckMenuItem  (hMenu,  wSelection,  MF_UNCHECKED)  ; 
wSelection  =  wParam  ; 

CheckMenuItem  (hMenu,  wSelection,  MF_CHECKED)  ; 


SetCl assWord  (hwnd,  GCW_HBRBACKGROUND, 

GetStockObject  (wColorlD  [wParam  -  I DM_WH ITE] ) ) 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

case  IDM_AB0UT  : 

MessageBox  (hwnd,  "Popup  Menu  Demonstration  Program." 

szAppName,  MB_I CON  I N  FORMATION  1  MB_0K)  ; 

return  0  ; 
case  I DM_EX I T  : 

SendMessage  (hwnd,  WM_CL0SE,  0,  0L)  ; 
return  0  ; 

case  IDM.HELP  : 

MessageBox  (hwnd,  "Help  not  yet  implemented!", 

szAppName,  MB_I CONEXCLAMATION  !  MB_0K)  ; 

return  0  ; 

} 

break  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
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POPMENU.RC 

/* . . 

POPMENU.RC  resource  script 

*/ 


#include  "popmenu.h" 


PopMenu  MENU 

{ 

POPUP  "" 

{ 

POPUP  "&File" 

{ 

MENUITEM  "&New", 

MENUITEM  "&0pen. . .", 

MENUITEM  "&Save" , 

MENUITEM  "Save  &As...", 
MENUITEM  SEPARATOR 
MENUITEM  "E&xit", 

} 

POPUP  "&Edit" 

{ 

MENUITEM  "&Undo" , 

MENUITEM  SEPARATOR 
MENUITEM  "Cu&t", 

MENUITEM  "&Copy", 

MENUITEM  "&Paste", 

MENUITEM  "De&lete", 

} 

POPUP  "&Background" 

{ 

MENUITEM  "&White" , 

MENUITEM  "&Lt  Gray", 

MENUITEM  "&Gray" , 

MENUITEM  "&Dk  Gray", 

MENUITEM  "&B1 ack", 

} 

POPUP  "&Hel p" 

{ 

MENUITEM  "&Help. . , 

MENUITEM  "&About  PopMenu...", 

} 

} 

} 


I DM_N  EW 
IDM.OPEN 
IDM.SAVE 
IDM.SAVEAS 

IDM_EXIT 


IDMJJNDO 

IDM_CUT 

IDM_C0PY 

IDM_PASTE 

IDM.DEL 


IDM_WHITE,  CHECKED 
IDM_LTGRAY 
IDM_GRAY 
IDM_DKGRAY 
I DM_B  LACK 


IDM.HELP 

IDM.AB0UT 
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POPMENU.H 


/* . - . 

POPMENU.H  header  file 


//define 

IDM.NEW 

1 

//define 

IDM_0PEN 

2 

//define 

IDM.SAVE 

3 

//define 

I DM_SAV  EAS 

4 

//define 

I DM_EX I T 

5 

//define 

IDMJJNDO 

10 

//define 

IDM.CUT 

11 

//define 

IDM.COPY 

12 

//define 

IDM_PASTE 

13 

//define 

IDM.DEL 

14 

//define 

I DM_WH ITE 

20 

//define 

IDM.LTGRAY 

21 

//define 

IDM.GRAY 

22 

//define 

IDM_DKGRAY 

23 

//define 

I DM_B  LACK 

24 

//define 

I DM_H  E  LP 

30 

//define 

IDM_AB0UT 

31 

POPMENU.DEF 


POPMENU.DEF  module  definition  file 


NAME  POPMENU 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Popup  Menu  Demonstration  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 
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The  POPMENU.RC  resource  script  defines  a  menu  very  similar  to  the  one  in  MENU- 
DEMO.  RC.  The  difference  is  that  the  top-level  menu  contains  only  one  item — a  popup  that 
invokes  the  File,  Edit,  Background,  and  Help  options. 

During  the  WM -CREATE  message  in  WndProc ,  POPMENU  obtains  a  handle  to  this 
popup  menu: 

hMenu  =  LoadMenu  (hlnst,  szAppName)  ; 

hMenu  =  GetSubMenu  (hMenu,  0)  ; 

During  the  WM_RBUTTONDOWN  message,  POPMENU  obtains  the  position  of  the 
mouse  pointer,  converts  the  position  to  screen  coordinates,  and  passes  the  coordinates  to 
TrackPopupMenu : 

point  =  MAKEPOINT  (IParam)  ; 

Cl ientToScreen  (hwnd,  & p o i n t )  ; 

TrackPopupMenu  (hMenu,  0,  point. x,  point. y,  0,  hwnd,  NULL)  ; 

Windows  then  displays  the  popup  menu  with  the  items  File,  Edit,  Background,  and 
Help.  Selecting  any  of  these  options  causes  the  nested  popup  menus  to  appear  to  the  right. 
The  menu  functions  the  same  as  a  normal  menu. 

Using  the  System  Menu 

Parent  windows  created  with  a  style  that  includes  WS-SYSMENU  have  a  system  menu  box 
at  the  left  of  the  caption  bar.  If  you  like,  you  can  modify  this  menu.  For  instance,  you  can 
add  your  own  menu  commands  to  the  system  menu.  While  this  is  not  recommended, 
modifying  the  system  menu  is  often  a  quick-and-dirty  way  to  add  a  menu  to  a  short  pro¬ 
gram  without  defining  it  in  the  resource  script.  The  only  restriction  is  this:  The  ID  numbers 
you  use  to  add  commands  to  the  system  menu  must  be  lower  than  F000H.  Otherwise,  they 
will  conflict  with  the  IDs  that  Windows  uses  for  the  normal  system  menu  commands.  And 
remember:  When  you  process  WM-SYSCOMMAND  messages  in  your  window  procedure 
for  these  new  menu  items,  you  must  pass  the  other  WM_SYSCOMMAND  messages 
to  DefWindowProc.  If  you  don’t,  you’ll  effectively  disable  all  normal  options  on  the  sys¬ 
tem  menu. 

The  program  POORMENU  (“Poor  Person’s  Menu”),  shown  in  Figure  9-6  beginning 
on  the  following  page,  adds  a  separator  bar  and  three  commands  to  the  system  menu.  The 
last  of  these  commands  removes  the  additions. 


363 


SECTION  III:  USING  RESOURCES 


POORMENU.MAK 

# 

//  POORMENU.MAK  make  file 

# 

poormenu.exe  :  poormenu.obj  poormenu.def 

$(WINLINK)  poormenu,  poormenu,  NUL,  $(WINLIB),  poormenu 
rc  -t  poormenu.exe 

poormenu.obj  :  poormenu. c 
$ ( WI NCC )  poormenu. c 


POORMENU.C 

/* . 

POORMENU.C  --  The  Poor  Person’s  Menu 

(c)  Charles  Petzold,  1992 
. */ 


//include  <windows.h> 

//define  IDM_AB0UT  1 
//define  IDM.HELP  2 
//define  IDM_REMOVE  3 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


static  char  szAppName  []  =  "PoorMenu"  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HMENU  hMenu  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbCl sExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 


=  CS.HREDRAW  !  CS.VREDRAW  ; 
=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 


Figure  9-6.  The  POORMENU  program. 


(continued) 
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wndclass.hlcon  =  Loadlcon  (NULL,  IDI_APPLICATION)  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass.hbrBackground  =  GetStockObject  (WHITE.BRUSH)  ; 
wndclass.lpszMenuNaine  =  NULL  ; 
wndclass.lpszClassNane  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "The  Poor  Person's  Menu", 
WSJDVERLAPPEDWINDOW, 

CWJJSEDEFAULT,  CW_USEDE FAU LT , 

CWJJSEDEFAULT,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

hMenu  =  GetSystemMenu  (hwnd,  FALSE)  ; 

AppendMenu  (hMenu,  MF.SEPARATOR,  0,  NULL)  ; 

AppendMenu  (hMenu,  MF.STRING,  IDM_AB0UT,  "About...")  ; 

AppendMenu  (hMenu,  MF_STRING,  I DM_H ELP ,  "Help...")  ; 

AppendMenu  (hMenu,  MF_STRING,  IDM.REMOVE,  "Remove  Additions")  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM.SYSCOMMAND  : 
switch  (wParam) 

{ 

case  IDM.ABOUT  : 

MessageBox  (hwnd,  "The  Poor  Person's  Menu  Program.", 
szAppName,  MB  JDK  !  MB_I CONI N  FORMAT ION)  ; 

return  0  ; 
case  IDM.HELP  : 

MessageBox  (hwnd,  "Help  not  yet  implemented!", 

szAppName,  MB  JDK  !  MB_I CONEXC LAMAT I ON )  ; 

return  0  ; 


(continued) 
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case  IDM.REMOVE  : 

GetSystemMenu  (hwnd,  TRUE)  ; 
return  0  ; 

} 

break  ; 

case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


POORMENU.DEF 


POORMENU. DEF  module  definition  file 


NAME  POORMENU 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'The  Poor  Persons  Menu  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


The  three  menu  IDs  are  defined  near  the  top  of  POORMENU.C: 

//define  IDM.ABOUT  1 
//define  IDM_HELP  2 
//define  IDM_REMOVE  3 

After  the  program’s  window  has  been  created,  POORMENU  obtains  a  handle  to  the  system 
menu: 

hMenu  =  GetSystemMenu  (hwnd,  FALSE)  ; 

When  you  first  call  GetSystemMenu ,  you  should  set  the  second  parameter  to  FALSE  in 
preparation  for  modifying  the  menu. 

The  menu  is  altered  with  four  AppendMenu  calls: 

AppendMenu  (hMenu,  MF_SE PARATOR ,  0,  NULL)  ; 

AppendMenu  (hMenu,  MF.STRING,  IDM.ABOUT,  "About...")  ; 

AppendMenu  (hMenu,  MF.STRING,  IDM_HELP ,  "Help...")  ; 

AppendMenu  (hMenu,  MF.STRING,  IDM_REMOVE,  "Remove  Additions")  ; 
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The  first  AppendMenu  call  adds  the  separator  bar.  Choosing  the  Remove  Additions  menu 
item  causes  POORMENU  to  remove  these  additions,  which  it  accomplishes  simply  by  call¬ 
ing  GetSystemMenu  again  with  the  second  parameter  set  to  TRUE: 

GetSystemMenu  (hwnd,  TRUE)  ; 

The  standard  system  menu  has  the  options  Restore,  Move,  Size,  Minimize,  Maximize, 
Close,  and  Switch  To.  These  generate  WM_SYSCOMMAND  messages  with  wParam  equal 
to  SC-RESTORE,  SC-MOVE,  SC-SIZE,  SC-MINIMUM,  SC_MAXIMUM,  SC-CLOSE,  and 
SC -TASKLIST.  Although  Windows  programs  do  not  normally  do  so,  you  can  process  these 
messages  yourself  rather  than  pass  them  on  to  DefWindowProc.  You  can  also  disable  or 
remove  some  of  these  standard  options  from  the  system  menu  using  methods  described 
below.  The  Windows  documentation  also  includes  some  standard  additions  to  the  system 
menu.  These  use  the  identifiers  SC-NEXTWINDOW,  SC-PREVWINDOW,  SC-VSCROLL, 
SC-HSCROLL,  and  SC-ARRANGE.  You  might  find  it  appropriate  to  add  these  commands 
to  the  system  menu  in  some  applications. 

Changing  the  Menu 

We’ve  already  seen  how  the  AppendMenu  function  can  be  used  to  define  a  menu  entirely 
within  a  program  and  to  add  menu  items  to  the  system  menu.  Prior  to  Windows  3,  you 
would  have  been  forced  to  use  the  ChangeMenu  function  for  this  job.  ChangeMenu  was  so 
versatile  that  it  was  one  of  the  most  complex  functions  in  all  of  Windows.  In  Windows  3, 
ChangeMenu  is  still  available,  but  its  functionality  has  been  divided  among  five  new 
functions: 

■  AppendMenu — adds  a  new  item  to  the  end  of  a  menu. 

■  DeleteMenu — deletes  an  existing  item  from  a  menu  and 
destroys  the  item. 

■  InsertMenu — inserts  a  new  item  into  a  menu. 

■  ModifyMenu — changes  an  existing  menu  item. 

■  RemoveMenu — removes  an  existing  item  from  a  menu. 

The  difference  between  DeleteMenu  and  RemoveMenu  is  important  if  the  item  is  a 
popup  menu.  DeleteMenu  destroys  the  popup  menu — but  RemoveMenu  does  not. 

Other  Menu  Commands 

Here  are  some  more  functions  useful  for  working  with  menus: 

When  you  change  a  top-level  menu  item,  the  change  is  not  shown  until  Windows 
redraws  the  menu  bar.  You  can  force  this  redrawing  by  calling: 

DrawMenuBar  (hwnd)  ; 
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Notice  that  the  parameter  to  DrawMenuBar  is  a  handle  to  the  window  rather  than  a  handle 
to  the  menu. 

You  can  obtain  the  handle  to  a  popup  menu  using: 

hMenuPopup  =  GetSubMenu  (hMenu,  nPosition)  ; 

where  nPosition  is  the  index  (starting  at  0)  of  the  popup  within  the  top-level  menu  indi¬ 
cated  by  hMenu.  You  can  then  use  the  popup  menu  handle  with  other  functions  (such  as 
AppendMenu). 

You  can  obtain  the  current  number  of  items  in  a  top-level  or  popup  menu  using: 

nCount  =  GetMenuItemCount  (hMenu)  ; 

You  can  obtain  the  menu  ID  for  an  item  in  a  popup  menu  from: 

wID  =  GetMenuItemID  (hMenuPopup,  nPosition)  ; 

where  nPosition  is  the  position  (starting  at  0)  of  the  item  within  the  popup. 

In  MENUDEMO  you  saw  how  to  check  or  uncheck  an  item  in  a  popup  menu  using: 

CheckMenuItem  (hMenu,  wID,  wCheck)  ; 

In  MENUDEMO,  hMenu  was  the  handle  to  the  top-level  menu,  wID  was  the  menu  ID,  and 
the  value  of  wCheck  was  either  MF_CHECKED  or  MF_UNCHECKED.  If  hMenu  is  a  handle 
to  a  popup  menu,  then  the  wID  parameter  can  be  a  positional  index  rather  than  a  menu  ID. 
If  an  index  is  more  convenient,  you  include  MF_BYPOSITION  in  the  third  parameter. 
For  instance: 

CheckMenuItem  (hMenu,  nPosition,  M F_CH ECKED  !  M F_BY POS I T I ON )  ; 

The  EnableMenuItem  function  works  similarly  to  CheckMenuItem  except  the  third 
parameter  is  MF_ENABLED,  MF_DISABLED,  or  MF_GRAYED.  If  you  use  EnableMenu- 
Item  on  a  top-level  menu  item  that  has  a  popup,  you  must  also  use  the  MF-BYPOSITION 
identifier  in  the  third  parameter  because  the  menu  item  has  no  menu  ID.  We’ll  see  an  ex¬ 
ample  of  EnableMenuItem  in  the  POPPAD  program  shown  later  in  this  chapter.  Hilite- 
Menultem  is  similar  to  CheckMenuItem  and  EnableMenuItem  but  uses  MF_HILITE  and 
MF_UNHILITE.  This  highlighting  is  the  reverse  video  that  Windows  uses  when  you  move 
among  menu  items.  You  do  not  normally  need  to  use  HiliteMenuItem. 

What  else  do  you  need  to  do  with  your  menu?  Have  you  forgotten  what  character 
string  you  used  in  a  menu?  You  can  refresh  your  memory  by  calling: 

nByteCount  =  GetMenuStri ng  (hMenu,  wID,  IpString,  nMaxCount,  wFlag)  ; 

The  wFlag  is  either  MF_BYCOMMAND  (where  wID  is  a  menu  ID)  or  MF_BYPOSITION 
(wID  is  a  positional  index).  The  function  copies  up  to  nMaxCount  bytes  of  the  character 
string  into  IpString  and  returns  the  number  of  bytes  copied. 
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Or  perhaps  you’d  like  to  know  what  the  current  flags  of  a  menu  item  are: 
wFlags  =  GetMenuState  (hMenu,  wID,  wFlag)  ; 

Again,  wFlag  is  either  MF_BYCOMMAND  or  MF_  BY  POSIT  ION.  The  wFlags  parameter  is  a 
combination  of  all  the  current  flags.  You  can  determine  the  current  flags  by  testing  against 
the  MF.DISABLED,  MF_ GRAYED,  MF_CHECKED,  MF_MENUBREAK,  MF_MENUBAR- 
BREAK,  and  MF_SEPARATOR  identifiers. 

Or  maybe  by  this  time  you’re  a  little  fed  up  with  menus.  In  that  case  you’ll  be  pleased 
to  know  that  if  you  no  longer  need  a  menu  in  your  program,  you  can  destroy  it: 

DestroyMenu  (hMenu)  ; 

This  invalidates  the  menu  handle. 

An  Unorthodox  Approach  to  Menus 

Now  let’s  step  a  little  off  the  beaten  path.  Instead  of  having  drop-down  menus  in  your  pro¬ 
gram,  how  about  creating  multiple  top-level  menus  without  any  popups  and  switching  be¬ 
tween  the  top-level  menus  using  the  SetMenu  call?  The  NOPOPUPS  program,  shown  in 
Figure  9-7,  demonstrates  how  to  do  it.  This  program  includes  File  and  Edit  items  similar  to 
those  that  MENUDEMO  uses  but  displays  them  as  alternate  top-level  menus. 

NOPOPUPS.MAK 

# 

#  NOPOPUPS.MAK  make  file 
#- 

nopopups.exe  :  nopopups.obj  nopopups.def  nopopups.res 

$(WINLINK)  nopopups,  nopopups,  NUL,  S(WINLIB),  nopopups 
rc  -t  nopopups.res 

nopopups.obj  :  nopopups. c  nopopups. h 
$ ( WI NCC )  nopopups. c 

nopopups.res  :  nopopups. rc  nopopups. h 
$ ( WI NRC )  nopopups. rc 

Figure  9-7.  The  NOPOPUPS  program. 
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NOPOPUPS.C 


/*-- - - - - - 

NOPOPUPS.C  --  Demonstrates  No-Popup  Nested  Menu 
(c)  Charles  Petzold,  1992 

- - */ 


#include  <windows.h> 

^include  "nopopups.h" 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "NoPopUps"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. IpszMenuName 
wndclass. 1 pszCl assName 


CS.HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  I D I _A P P L I CAT ION)  ; 
LoadCursor  (NULL,  IDC.ARR0W)  ; 
GetStockObject  ( WH I TE_B RUSH )  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "No-Popup  Nested  Menu  Demonstration", 
WS.OVERLAPPEDWINDOW, 

CW.USEDEFAULT,  CW.USEDEFAULT, 

CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 
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DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HMENU  hMenuMain,  hMenuEdit,  hMenuFile  ; 

HANDLE  hlnstance  ; 


switch  (message) 

{ 

case  WM.CREATE  : 

hlnstance  =  GetWindowWord  (hwnd,  GWW_HI NSTANCE )  ; 


hMenuMain  =  LoadMenu  (hlnstance,  "MenuMain") 
hMenuFile  =  LoadMenu  (hlnstance,  "MenuFile") 
hMenuEdit  =  LoadMenu  (hlnstance,  "MenuEdit”) 


SetMenu  (hwnd,  hMenuMain)  ; 
return  0  ; 


case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  IDM.MAIN  : 

SetMenu  (hwnd,  hMenuMain)  ; 
return  0  ; 

case  IDM.FILE  : 

SetMenu  (hwnd,  hMenuFile)  ; 
return  0  ; 

case  IDM.EDIT  : 

SetMenu  (hwnd,  hMenuEdit)  ; 
return  0  ; 

case  IDM.NEW  : 
case  IDM.OPEN  : 
case  IDM.SAVE  : 
case  IDM.SAVEAS  : 
case  IDM.UNDO  : 
case  IDM.CUT  : 
case  IDM.COPY  : 
case  IDM.PASTE  : 
case  IDM.DEL  : 

MessageBeep  (0)  ; 
return  0  ; 

} 
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break  ; 

case  WM_DESTROY  : 

SetMenu  (hwnd,  hMenuMain)  ; 

DestroyMenu  (hMenuFile)  ; 

DestroyMenu  (hMenuEdit)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam) 

} 


NOPOPUPS.RC 


/*- 


NOPOPUPS.RC  resource  script 


-*/ 


#include  "nopopups.h" 


MenuMain  MENU 
{ 

MENUITEM 

"MAIN:”, 

0. 

MENUITEM 

"&File...\ 

I DM_F I LE 

MENUITEM 

} 

MenuFile  MENU 
{ 

MENUITEM 

"&Edit. . , 

I DM_ED I T 

"FILE:", 

0, 

MENUITEM 

"&New", 

I DM_NEW 

MENUITEM 

"&0pen. . 

IDM_0PEN 

MENUITEM 

"&Save" , 

IDM_SAVE 

MENUITEM 

"Save  &As. . 

I DM_SAV  EAS 

MENUITEM 

} 

MenuEdit  MENU 
{ 

MENUITEM 

"(&Main)" , 

IDM.MAIN 

"EDIT:", 

0, 

MENUITEM 

"&Undo", 

IDM.UNDO 

MENUITEM 

"Cu&t", 

IDM.CUT 

MENUITEM 

"&Copy", 

IDM.COPY 

MENUITEM 

"&Paste", 

IDM.PASTE 

MENUITEM 

"De&lete", 

IDM_DEL 

MENUITEM 

"(&Main)", 

IDM_MAIN 

INACTIVE 


INACTIVE 


INACTIVE 
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NOPOPUPS.H 


/*-- . 

NOPOPUPS.H  header  file 


#define 

IDM.NEW 

1 

#define 

I  DM__0PEN 

2 

#define 

IDM_SAVE 

3 

#define 

IDM.SAVEAS 

4 

#define 

IDM.UND0 

5 

#define 

IDM.CUT 

6 

#define 

IDM.C0PY 

7 

#define 

IDM.PASTE 

8 

#define 

IDM.DEL 

9 

#define 

IDM.MAIN 

10 

#define 

IDM_EDIT 

11 

#define 

IDM.FILE 

12 

NOPOPUPS.DEF 


NOPOPUPS. DEF  module  definition  file 


NAME  NOPOPUPS 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Demonstration  of  No-Popup  Menu  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


The  resource  script  has  three  menus  rather  than  one.  When  the  window  procedure  pro¬ 
cesses  the  WM -CREATE  message,  Windows  loads  each  menu  resource  into  memory: 

hMenuMain  =  LoadMenu  (hlnstance,  "MenuMain")  ; 
hMenuFile  =  LoadMenu  (hlnstance,  "MenuFile")  ; 
hMenuEdit  =  LoadMenu  (hlnstance,  "MenuEdit")  ; 

Initially,  the  program  displays  the  main  menu: 

SetMenu  (hwnd,  hMenuMain)  ; 
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The  main  menu  lists  the  three  options  using  the  character  strings  “MAIN:”,  “File 
and  “Edit. . However,  “MAIN:”  is  disabled,  so  it  doesn’t  cause  WM_COMMAND  messages 
to  be  sent  to  the  window  procedure.  The  File  and  Edit  menus  begin  “FILE:”  and  “EDIT:”  to 
identify  these  as  submenus.  The  last  item  in  each  menu  is  the  character  string  “(Main)”;  this 
option  indicates  a  return  to  the  main  menu.  Switching  among  these  three  menus  is  simple: 

case  WM_COMMAND  : 

switch  (wParam) 

{ 

case  IDM.MAIN  : 

SetMenu  (hwnd,  hMenuMain)  ; 
return  0  ; 

case  IDM_FILE  : 

SetMenu  (hwnd,  hMenuFile)  ; 
return  0  ; 

case  I DM_ED I T  : 

SetMenu  (hwnd,  hMenuEdit)  ; 
return  0  ; 

[other program  lines] 

} 

break  ; 

During  the  WM -DESTROY  message,  NOPOPUPS  sets  the  program’s  menu  to  the 
Main  menu  and  destroys  the  File  and  Edit  menus  with  calls  to  DestroyMenu.  The  Main 
menu  is  destroyed  automatically  when  the  window  is  destroyed. 


USING  BITMAPS  IN  MENUS 

Character  strings  are  not  the  only  way  to  display  a  menu  item.  You  can  also  use  a  bitmap.  If 
you  immediately  recoiled  at  the  thought  of  pictures  of  file  folders,  paste  jars,  and  trash  cans 
in  a  menu,  don’t  think  of  pictures.  Think  instead  of  how  useful  menu  bitmaps  might  be  for 
a  drawing  program.  Think  of  using  different  fonts  and  font  sizes,  line  widths,  hatch  pat¬ 
terns,  and  colors  in  your  menus. 

The  program  we’re  going  to  examine  is  called  GRAFMENU  (“graphics  menu”).  The 
top-level  menu  is  shown  in  Figure  9-8.  The  enlarged  block  letters  are  obtained  from  40- 
by-16-pixel  monochrome  bitmap  files  created  in  the  Microsoft  Image  Editor  and  saved  as 
.BMP  files;  they  could  be  pictures  instead.  Choosing  FONT  from  the  menu  invokes  a  popup 
containing  three  options — Courier  New,  Arial,  and  Times  New  Roman.  These  are  the  stan¬ 
dard  Windows  3.1  TrueType  fonts  and  each  is  displayed  in  its  respective  font  (Figure  9-9). 
These  bitmaps  were  created  in  the  program  using  a  technique  involving  a  “memory  device 
context.” 
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Figure  9-9.  The  GRAFMENU program  s popup  FONT  menu 
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Finally,  when  you  pull  down  the  system  menu,  you  see  that  you  have  access  to  some  “help” 
information,  with  the  word  “Help”  perhaps  mirroring  the  desperation  of  a  new  user 
(Figure  9-10).  This  64-by-64-pixel  monochrome  bitmap  was  created  in  the  Image  Editor. 


Program 

Manager 


Figure  9-10.  The  GRAFMENU program  s  system  menu. 

The  GRAFMENU  program,  including  the  four  bitmaps  created  in  the  Image  Editor,  is 
shown  in  Figure  9-11. 


GRAFMEHU.MAK 

# 

#  GRAFMENU. MAK  make  file 

# 

grafmenu.exe  :  grafmenu.obj  grafmenu.def  grafmenu.res 

$ (WINLINK)  grafmenu,  grafmenu,  NUL,  l(WINLIB),  grafmenu 
rc  -t  -31  grafmenu.res 

grafmenu.obj  :  grafmenu. c  grafmenu. h 
KWINCC)  grafmenu. c 

grafmenu.res  :  grafmenu. rc  grafmenu. h  \ 

editlabl.bmp  filelabl.bmp  fontlabl.bmp  bighelp.bmp 
S(WINRC)  grafmenu. rc 


Figure  9-1 1 .  The  GRAFMENU  program. 
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GRAFMENU.C 

/* . . 

GRAFMENU.C  --  Demonstrates  Bitmap  Menu  Items 
(c)  Charles  Petzold,  1992 
. . . . . */ 

//include  <windows.h> 

//include  <string.h 
//include  "grafmenu.h" 

long  FAR  PASCAL  .export  WndProc  ( HWND ,  UINT.  UINT,  LONG)  ; 

HBITMAP  StretchBitmap  (HBITMAP)  ; 

HBITMAP  GetBitmapFont  (int)  ; 

char  szAppName  []  =  "GrafMenu"  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HBITMAP  hBitmapHelp,  hBitmapFile,  hBitmapEdit, 
hBitmapFont,  hBitmapPopFont  [3]  ; 

HMENU  hMenu,  hMenuPopup  ; 

HWND  hwnd  ; 

int  i  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

( 

wndclass. style  =  CS.HREDRAW  i  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

wndclass. cbWndExtra  =  0  ; 

wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  Loadlcon  (NULL,  I DI_APPLI CATION )  ; 

wndclass. hCursor  =  LoadCursor  (NULL,  IDC.ARR0W)  ; 

wndclass. hbrBackground  =  GetStockObject  (WHITE.BRUSH)  ; 
wndclass. IpszMenuName  =  NULL  ; 
wndclass. 1 pszCl assName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hMenu  =  CreateMenu  ()  ; 

hMenuPopup  =  LoadMenu  (hlnstance,  "MenuFile")  ; 

hBitmapFile  =  StretchBitmap  (LoadBitmap  (hlnstance,  "BitmapFile"))  ; 

(continued) 
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AppendMenu  (hMenu,  MF_BITMAP  !  MF_P0PUP,  hMenuPopup, 

( LPSTR)  (LONG)  hBitmapFile)  ; 

hMenuPopup  =  LoadMenu  (hlnstance,  "MenuEdit")  ; 

hBi tmapEdi t  =  StretchBitmap  ( LoadBi tmap  (hlnstance,  "BitmapEdit"))  ; 

AppendMenu  (hMenu,  MF.BITMAP  !  MF_P0PUP,  hMenuPopup, 

(LPSTR)  (LONG)  hBi tmapEdi t)  ; 

hMenuPopup  =  CreateMenu  0  ; 

for  (i  =  0  ;  i  <  3  ;  i++) 

{ 

hBitmapPopFont  [i]  =  GetBitmapFont  (i)  ; 

AppendMenu  (hMenuPopup,  MF.BITMAP,  IDM_C0UR  +  i, 

(LPSTR)  (LONG)  hBitmapPopFont  [i ] )  ; 

} 

hBitmapFont  =  StretchBitmap  (LoadBitmap  (hlnstance,  "BitmapFont") )  ; 
AppendMenu  (hMenu,  MF.BITMAP  !  MF.POPUP,  hMenuPopup, 

(LPSTR)  (LONG)  hBitmapFont)  ; 

hwnd  =  CreateWindow  (szAppName,  "Bitmap  Menu  Demonstration", 

WS_0V  ERLAPPEDWI NDOW , 

CW.JJSEDEFAULT,  CWJJSEDEFAULT, 

CWJJSEDEFAULT,  CW_USEDEFAULT, 

NULL,  hMenu,  hlnstance,  NULL)  ; 

hMenu  =  GetSystemMenu  (hwnd,  FALSE)  ; 

hBitmapHelp  =  StretchBitmap  (LoadBitmap  (hlnstance,  "BitmapHelp"))  ; 
AppendMenu  (hMenu,  MF_SEPARATOR,  NULL,  NULL)  ; 

AppendMenu  (hMenu,  MF_B I TMAP ,  IDM.HELP,  (LPSTR)  (LONG)  hBitmapHelp)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

DeleteObject  (hBitmapHelp)  ; 

DeleteObject  ( hBi tmapEdi t )  ; 

DeleteObject  (hBitmapFile)  ; 

DeleteObject  (hBitmapFont)  ; 

for  (i  =  0  ;  i  <  3  ;  i++) 

DeleteObject  (hBitmapPopFont  [ i ] )  ; 

return  msg.wParam  ; 

} 
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HBITMAP  StretchBitmap  (HBITMAP  hBitnapl) 

{ 

BITMAP  bml ,  bm2  ; 

HBITMAP  hBi tmap2  ; 

HDC  hdc,  hdcMeml.  hdcMem2  ; 

TEXTMETRIC  tin  ; 

hdc  =  CreateIC  ("DISPLAY”,  NULL,  NULL.  NULL)  ; 

GetTextMetrics  (hdc,  &tm)  ; 
hdcMeml  =  CreateCompatibleDC  (hdc)  ; 
hdcMem2  =  CreateCompatibleDC  (hdc)  ; 

DeleteDC  (hdc)  ; 

GetObject  (hBitmapl,  sizeof  (BITMAP),  ( LPSTR)  &bml)  ; 
bm2  =  bml  ; 

bm2.bmWidth  =  (tm.tmAveCharWidth  *  bm2.bmWidth)  /  4  ; 

bm2.bmHeight  =  (tm.tmHeight  *  bm2.bmHeight)  /  8  ; 

bm2.bmWidthBytes  =  ( ( bm2 . bmWi dth  +  15)  /  16)  *  2  ; 

hBitmap2  =  CreateBi tmaplndi rect  (&bm2)  ; 

SelectObject  (hdcMeml,  hBitmapl)  ; 

SelectObject  (hdcMem2,  hBi tmap2 )  ; 

StretchBl t  (hdcMem2,  0,  0,  bm2.bmWidth,  bm2.bmHeight, 

hdcMeml,  0,  0,  bml.bmWidth,  bml.bmHeight,  SRCCOPY)  ; 

DeleteDC  (hdcMeml)  ; 

DeleteDC  (hdcMem2)  ; 

DeleteObject  (hBitmapl)  ; 

return  hBitmap2  ; 

} 

HBITMAP  GetBitmapFont  (int  i) 

{ 

static  char  *szFaceName[3]  =  {  "Courier  New",  "Arial", 

"Times  New  Roman"  }  ; 

static  LOGFONT  If  ; 

DWORD  dwSize  ; 

HBITMAP  hBitmap  ; 

HDC  hdc,  hdcMem  ; 

HFONT  hFont  ; 

TEXTMETRIC  tm  ; 

RECT  rc  ; 

hdc  =  CreateIC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 

GetTextMetrics  (hdc,  &tm)  ; 
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lf.lfHeight  =  2  *  tm.tmHeight  ; 

strcpy  ((char  *)  If .IfFaceName,  szFaceName[i])  ; 

hdcMem  =  CreateCompatibleDC  (hdc)  ; 

SelectObject  (hdcMem,  CreateFontlndi rect  (&1 f ) )  ; 

dwSize  =  GetTextExtent  (hdcMem,  szFaceName[i ] ,  strlen  (szFaceName[i]))  ; 

hBitmap  =  CreateBi tmap  ( LOWORD  (dwSize),  HIWORD  (dwSize).  1,  1,  NULL)  ; 
SelectObject  (hdcMem,  hBitmap)  ; 

rc.left  =  0  ; 

rc.top  =  0  ; 

rc. right  =  LOWORD  (dwSize)  ; 

rc. bottom  =  HIWORD  (dwSize)  ; 

Fill Rect  (hdcMem,  &rc,  GetStockObject  (WHITE.BRUSH) )  ; 

TextOut  (hdcMem,  0,  0,  szFaceName[i ] ,  strlen  (szFaceName[i ] ) )  ; 

DeleteDC  (hdcMem)  ; 

DeleteDC  (hdc)  ; 

DeleteObject  ( h Font )  ; 

return  hBitmap  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

HMENU  hMenu  ; 

static  short  nCurrentFont  =  IDM.COUR  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

CheckMenuItem  (GetMenu  (hwnd),  nCurrentFont,  MF.CHECKED)  ; 
return  0  ; 

case  WM.SYSCOMMAND  : 
switch  (wParam) 

{ 

case  IDM.HELP  : 

MessageBox  (hwnd,  "Help  not  yet  implemented.", 

szAppName,  MB_0K  !  MB.ICONEXCLAMATION)  ; 

return  0  ; 

} 

break  ; 

case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  IDM.NEW  : 
case  IDM.OPEN  : 
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case  IDM_SAVE  : 
case  IDM_SAVEAS  : 
case  IDM_UND0  : 
case  IDM_CUT  : 
case  IDM.C0PY  : 
case  IDM.PASTE  : 
case  IDM_DEL  : 

MessageBeep  (0)  ; 
return  0  ; 

case  IDM.C0UR  : 
case  IDM_ARIAL  : 
case  I DM_TI MES  : 

hMenu  =  GetMenu  (hwnd)  ; 

CheckMenuItem  (hMenu,  nCurrentFont ,  MF_UNCH ECKED )  ; 
nCurrentFont  =  wParam  ; 

CheckMenuItem  (hMenu,  nCurrentFont,  MF_CHECKED)  ; 
return  0  ; 

} 

break  ; 

case  WMJJESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


GRAFMENU.RC 


GRAFMENU. RC  resource  script 
. - . */ 

//include  "grafmenu.h" 

BitmapEdit  BITMAP  editlabl.bmp 
BitmapFile  BITMAP  filelabl.bmp 
BitmapFont  BITMAP  fontlabl.bmp 
BitmapHelp  BITMAP  bighelp.bmp 

MenuFile  MENU 
l 

MENUITEM  "ANew",  IDM_NEW 

MENUITEM  "&0pen. . IDM_0PEN 
MENUITEM  "&Save",  IDM_SAVE 

MENUITEM  "Save  &As...",  IDM_SAVEAS 
} 
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MenuEdit  MENU 

{ 

MENUITEM  "&Undo",  IDMJJNDO 

MENUITEM  SEPARATOR 
MENUITEM  "Cu&t",  IDM.CUT 

MENUITEM  "&Copy",  IDM.COPY 

MENUITEM  "&Paste”,  IDM_PASTE 

MENUITEM  "De&lete”.  IDM.DEL 

} 


GRAFMENU.H 


GRAFMENU.H  header  file 

. */ 

#def i ne  I DM_NEW  1 
//define  IDM_0PEN  2 
//def  i ne  IDM_SAVE  3 
//define  IDM_SAVEAS  4 

#define  IDM_UND0  5 
//define  IDM_CUT  6 
//define  IDM_C0PY  7 
//define  IDM_PASTE  8 
//define  IDM_DEL  9 

//define  IDM_C0UR  10 
//define  IDM_ARIAL  11 
//define  IDM_TIMES  12 

//define  I DM_H E L P  13 


EDITLABL.BMP 
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FILELABL.BMP 

FILE 


FONTLABL.BMP 

FONT 


BIGHELP.BMP 


GRAFMENU.DEF 


;  GRAFMENU.DEF  module  definition  file 


NAME  GRAFMENU 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Demonstrates  Bitmap  Menu  Items  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 
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To  examine  the  subject  of  bitmaps  and  menus  in  the  detail  it  deserves,  we’ll  need  to 
cross  the  border  into  GDI  territory — a  full  exploration  of  which  awaits  us  in  the  next  sec¬ 
tion  of  this  book.  The  discussion  here  will  serve  as  a  preview  of  topics  that  we’ll  return  to 
again  in  Chapter  11. 

Two  Methods  of  Creating  Bitmaps  for  Menus 

To  insert  a  bitmap  into  a  menu,  you  use  AppendMenu  or  InsertMenu.  Where  does  this  bit¬ 
map  come  from?  It  can  come  from  one  of  two  places.  First,  you  can  create  a  bitmap  using 
the  Image  Editor  and  include  the  bitmap  file  in  your  resource  script.  Within  the  program, 
you  can  use  LoadBitmap  to  load  the  bitmap  resource  into  memory  and  use  AppendMenu 
or  InsertMenu  to  attach  it  to  the  menu.  There’s  a  problem  with  this  approach,  however. 
The  bitmap  will  not  be  suitable  for  all  types  of  video  resolutions  and  aspect  ratios;  you 
have  to  stretch  the  loaded  bitmap  to  account  for  this.  Alternatively,  you  can  create  the  bit¬ 
map  right  in  the  program  and  attach  it  to  the  menu. 

Both  of  these  methods  sound  a  lot  more  difficult  than  they  actually  are.  We  don’t  have 
to  mess  around  with  the  actual  bits  themselves.  Windows  provides  functions  that  let  us 
manipulate  bitmaps  cleanly  using  something  called  the  “memory  device  context.” 

The  Memory  Device  Context 

When  you  use  GDI  calls  (such  as  TextOut )  to  write  on  the  client  area  of  your  window, 
you’re  actually  writing  to  a  block  of  memory  (the  video  display  memory)  that  is  organized 
much  like  a  giant  bitmap.  The  width  and  height  of  this  bitmap  are  equal  to  the  resolution  of 
the  video  display.  The  manner  in  which  multiple  bits  define  color  is  also  defined  by  the 
video  adapter.  If  you  think  about  it,  Windows  should  also  be  able  to  pretend  that  a  block  of 
regular  memory  is  video  display  memory.  It  should  be  able  to  write  to  this  memory  the 
same  way  it  writes  on  the  screen.  We  should  then  be  able  to  use  this  block  of  memory  as 
a  bitmap. 

That’s  exactly  what  a  memory  device  context  is.  It  helps  us  draw  on  and  manipulate 
bitmaps  in  a  Windows  program.  Here  are  the  steps  involved: 

1.  Create  a  memory  device  context  using  the  CreateCompatibleDC  call. 

Initially,  the  display  surface  of  this  memory  device  context  contains  one 
monochrome  pixel.  You  can  think  of  this  device  context  as  being  1  pixel 
high  and  1  pixel  wide,  with  two  colors  (black  and  white). 

2.  Create  an  uninitialized  bitmap  using  CreateBitmap,  CreateBitmapIn- 
direct ,  or  CreateCompatibleBitmap.  When  you  create  the  bitmap,  you 
specify  the  height  and  width  and  the  color  organization.  However,  the 
pixels  of  the  bitmap  need  not  actually  represent  anything  yet.  Save  the 
handle  to  the  bitmap. 
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3.  Select  the  bitmap  into  the  memory  device  context  using  SelectObject.  Now 
the  memory  device  context  has  a  display  surface  that  is  the  size  of  the 
bitmap  with  the  same  number  of  colors  as  defined  by  the  bitmap. 

4.  Use  GDI  functions  to  draw  on  the  memory  device  context  the  same  way 
you  use  GDI  functions  to  draw  on  a  normal  device  context.  Anything  you 
draw  within  the  display  surface  of  the  memory  device  context  is  actually 
drawn  on  the  bitmap  selected  into  the  device  context. 

5.  Delete  the  memory  device  context.  You  are  left  with  a  handle  to  a  bitmap 
that  contains  a  pixel  representation  of  what  you  drew  on  the  memory 
device  context. 

Creating  a  Bitmap  with  Text 

The  GetBitmapFont  function  in  GRAFMENU  takes  a  parameter  of  0,  1,  or  2  and  returns  a 
handle  to  a  bitmap.  This  bitmap  contains  the  string  “Courier  New,”  “Arial,”  or  “Times  New 
Roman”  in  the  appropriate  font  and  about  twice  the  size  of  the  normal  system  font.  Let’s 
see  how  GetBitmapFont  does  it.  (The  code  that  follows  is  not  the  same  as  that  in  the 
GRAFMENU.C  file.  For  purposes  of  clarity,  I’ve  replaced  references  to  the  szFaceName 
array  with  the  values  appropriate  for  Arial.) 

The  first  step  is  to  get  a  handle  to  the  system  font  and  use  GetObject  to  copy  charac¬ 
teristics  of  that  font  into  the  structure  If  System,  which  has  type  LOGFONT  (“logical  font”): 

hFont  =  GetStockObject  (SYSTEM.FONT)  ; 

GetObject  (hFont,  sizeof  (LOGFONT),  ( LPSTR)  &lfSystem)  ; 

Certain  fields  of  this  logical  font  structure  must  be  modified  to  make  it  describe  a  larger 
Arial  font: 

If .lfHeight  *=  2  ; 

strcpy  (lf.lfFaceName,  "Arial")  ; 

The  next  step  is  to  get  a  device  context  for  the  screen  and  create  a  memory  device 
context  compatible  with  the  screen: 

hdc  =  CreateIC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 
hdcMem  =  CreateCompati bl eDC  (hdc)  ; 

The  handle  to  the  memory  device  context  is  hdcMem.  Next,  we  create  a  font  based  on  the 
modified  If  structure  and  select  that  font  into  the  memory  device  context: 

SelectObject  (hdcMem,  CreateFontlndi rect  (&lf))  ; 

Now  when  we  write  some  text  to  the  memory  device  context,  Windows  will  use  the  True¬ 
Type  Arial  font  selected  into  the  device  context. 
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But  this  memory  device  context  still  has  a  one-pixel  monochrome  device  surface.  We 
have  to  create  a  bitmap  large  enough  for  the  text  we  want  to  display  on  it.  You  can  obtain 
the  dimensions  of  the  text  through  GetTextExtent  and  create  a  bitmap  based  on  these 
dimensions  with  CreateBitmap : 

dwSize  =  GetTextExtent  (hdcMem,  "Arial",  5)  ; 

hBitmap  =  CreateBitmap  ( LOWORD  (dwSize),  H I  WORD  (dwSize),  1.  1,  NULL)  ; 
SelectObject  (hdcMem,  hBitmap)  ; 

This  device  context  now  has  a  monochrome  display  surface  exactly  the  size  of  the  text. 
Now  all  we  have  to  do  is  write  the  text  to  it.  You’ve  seen  this  function  before: 

TextOut  (hdcMem,  0,  0,  "Arial",  5)  ; 

We’re  finished  except  for  cleaning  up.  To  do  so,  we  select  the  system  font  (with 
handle  hFont)  back  into  the  device  context  using  SelectObject ,  and  we  delete  the  previous 
font  handle  that  SelectObject  returns,  which  is  the  handle  to  the  Arial  font: 

DeleteObject  (SelectObject  (hdcMem,  hFont))  ; 

Now  we  can  also  delete  the  two  device  contexts: 

DeleteDC  (hdcMem)  ; 

DeleteDC  (hdc)  ; 

We’re  left  with  a  bitmap  that  has  the  text  “Arial”  in  an  Arial  font. 

Scaling  Bitmaps 

The  memory  device  context  also  comes  to  the  rescue  when  we  need  to  scale  fonts  to  a  dif¬ 
ferent  display  resolution  or  aspect  ratio.  I  created  the  four  bitmaps  used  in  GRAFMENU  to 
be  the  correct  size  for  a  display  that  has  a  system  font  height  of  8  pixels  and  width  of  4  pix¬ 
els.  For  other  system  font  dimensions,  the  bitmap  has  to  be  stretched.  This  is  done  in 
GRAFMENU’s  StretchBitmap  function. 

The  first  step  is  to  get  the  device  context  for  the  screen,  obtain  the  text  metrics  for  the 
system  font,  and  create  two  memory  device  contexts: 

hdc  =  CreateIC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 

GetTextMetrics  (hdc,  &tm)  ; 
hdcMeml  =  CreateCompati bl eDC  (hdc)  ; 
hdcMem2  =  CreateCompati bl eDC  (hdc)  ; 

DeleteDC  (hdc)  ; 

The  bitmap  handle  passed  to  the  function  is  hBitmapl.  The  program  can  obtain  the  dimen¬ 
sions  of  this  bitmap  using  GetObject : 

GetObject  (hBitmapl,  sizeof  (BITMAP),  ( LPSTR)  &bml)  ; 

This  copies  the  dimensions  into  a  structure  bml  of  type  BITMAR  The  structure  bm2  is  set 
equal  to  bml ,  and  then  certain  fields  are  modified  based  on  the  system  font  dimensions: 
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bm2  =  bml  ; 

bm2.bmWidth  =  ( tm . tmAveCha rWi d th  *  bm2 . bmWi dth )  /  4  ; 

bm2.bmHeight  =  (tm.tmHeight  *  bm2.bmHeight)  /  8  ; 

bm2.bmWidthBytes  =  ( ( bm2 . bmWi dth  +  15)  /  16)  *  2  ; 

Then  a  new  bitmap  with  handle  hBitmap2  can  be  created  that  is  based  on  the  altered 
dimensions: 

hBi tmap2  =  CreateBi tmapl ndi rect  (&bm2)  ; 

You  can  then  select  these  two  bitmaps  into  the  two  memory  device  contexts: 

SelectObject  (hdcMeml,  hBi tmapl )  ; 

SelectObject  (hdcMem2,  hBi tmap2 )  ; 

We  want  to  copy  the  first  bitmap  to  the  second  bitmap  and  stretch  it  in  the  process. 
This  involves  the  StretchBlt  call: 

StretchBlt  (hdcMem2,  0,  0,  bm2 . bmWi dth ,  bm2 . bmHei ght , 

hdcMeml,  0,  0,  bml .bmWidth,  bml.bmHeight,  SRCCOPY)  ; 

Now  the  second  bitmap  has  the  properly  scaled  bitmap.  We’ll  use  that  one  in  the  menu. 
Cleanup  is  simple: 

DeleteDC  (hdcMeml)  ; 

DeleteDC  (hdcMem2)  ; 

DeleteObject  ( hBi tmapl )  ; 

Putting  the  Menu  Together 

GRAFMENU’s  WinMain  function  uses  the  StretchBitmap  and  GetBitmapFont  functions 
when  constructing  the  menu.  GRAFMENU  has  two  menus  already  defined  in  the  resource 
script.  These  will  become  popups  for  the  File  and  Edit  options. 

GRAFMENU  begins  by  obtaining  a  handle  to  an  empty  menu: 

hMenu  =  CreateMenu  0  ; 

The  popup  menu  for  File  (containing  the  four  options  New,  Open,  Save,  and  Save  As)  is 
loaded  from  the  resource  script: 

hMenuPopup  =  LoadMenu  (hlnstance,  "MenuFile")  ; 

The  bitmap  containing  the  word  “FILE”  is  also  loaded  from  the  resource  script  and 
stretched  using  StretchBitmap : 

hBi tmapFi 1 e  =  StretchBitmap  ( LoadBi tmap  (hlnstance,  "BitmapFile") )  ; 

The  bitmap  handle  and  popup  menu  handle  become  parameters  in  the  AppendMenu  call: 

AppendMenu  (hMenu,  M F_B I TMAP  !  MF.POPUP, 

hMenuPopup,  ( LPSTR)  (LONG)  hBi tmapFi 1 e )  ; 
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The  same  procedure  is  followed  for  the  Edit  menu: 

hMenuPopup  =  LoadMenu  (hlnstance,  "MenuEdit")  ; 

hBi tmapEdi t  =  StretchBi tmap  ( LoadBi tmap  (hlnstance,  "BitmapEdit") )  ; 

AppendMenu  (hMenu,  M F_B I TMAP  !  MF_P0PUP, 

hMenuPopup,  ( LPSTR)  (LONG)  hBi tmapEdi t)  ; 

The  popup  menu  for  the  three  fonts  is  constructed  from  calls  to  the  GetBitmapFont 
function: 

hMenuPopup  =  CreateMenu  0  ; 
for  (i  =  0  ;  i  <  3  ;  i++) 

{ 

hBitmapPopFont  [i]  =  GetBitmapFont  (i)  ; 

AppendMenu  (hMenuPopup,  M F_B I TMAP , IDM_C0UR  +  i, 

(LPSTR)  (LONG)  hMenuPopupFont  [i])  ; 

} 

The  popup  is  then  added  to  the  menu: 

hBitmapFont  =  StretchBi tmap  ( LoadBi tmap  (hlnstance,  "Bi tmapFont") )  ; 

AppendMenu  (hMenu,  MF_B ITMAP  MF_P0PUP,  hMenuPopup, 

(LPSTR)  (LONG)  hBitmapFont)  ; 

The  window  menu  is  complete.  Now  you  can  include  hMenu  in  the  CreateWindow  call: 

hwnd  =  CreateWindow  (szAppName,  "Bitmap  Menu  Demonstration", 

WS_0V  ERLAP  P  E  D , 

CW.USEDEFAULT,  CW_USEDEFAULT, 

CW.USEDEFAULT,  CWJJSEDEFAULT. 

NULL,  hMenu,  hlnstance,  NULL)  ; 

After  hwnd  is  available,  GRAFMENU  can  alter  the  system  menu.  GRAFMENU  first 
obtains  a  handle  to  it: 

hMenu  =  GetSystemMenu  (hwnd,  FALSE)  ; 

This  loads  the  “Help”  bitmap  and  stretches  it  to  an  appropriate  size: 

hBi tmapHel p  =  StretchBi tmap  ( LoadBi tma p  (hlnstance,  "BitmapHel p") )  ; 

This  adds  a  separator  bar  and  the  stretched  bitmap  to  the  system  menu: 

AppendMenu  (hMenu,  MF_SEPARATOR,  0,  NULL)  ; 

AppendMenu  (hMenu,  MF_B I TMAP ,  IDM.HELP,  (LPSTR)  (LONG)  hBi tmapHel p)  ; 

Remember  that  bitmaps  are  GDI  objects  and  must  be  explicitly  deleted  before  your 
program  terminates.  You  accomplish  this  after  GRAFMENU  exits  from  its  message  loop: 

DeleteObject  ( hBi tmapHel p )  ; 

DeleteObject  (hBi tmapEdi t )  ; 

DeleteObject  (hBi tmapFi 1 e )  ; 

DeleteObject  (hBitmapFont)  ; 
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I’ll  conclude  this  section  with  a  couple  of  miscellaneous  notes: 

■  In  a  top-level  menu,  Windows  adjusts  the  menu  bar  height  to  accommo¬ 
date  the  tallest  bitmap.  Other  bitmaps  (or  character  strings)  are  aligned  at 
the  top  of  the  menu  bar.  The  size  of  the  menu  bar  obtained  from: 

GetSystemMetrics  (SM_CYMENU) 

is  no  longer  valid  after  you  put  bitmaps  in  a  top-level  menu. 

■  As  you  can  see  from  playing  with  GRAFMENU,  you  can  use  check  marks 
with  bitmapped  menu  items  in  popups,  but  the  check  mark  is  of  normal 
size.  If  that  bothers  you,  you  can  create  a  customized  check  mark  and  use 
SetMenuItemBitmaps. 

■  Another  approach  to  using  non-text  (or  text  in  a  font  other  than  the  sys¬ 
tem  font)  on  a  menu  is  the  “owner-draw”  item.  The  Windows  Guide  to 
Programming  discusses  this  approach. 

Adding  a  Keyboard  Interface 

Now  we  have  another  problem.  When  the  menu  contains  text,  Windows  automatically  adds 
a  keyboard  interface.  You  can  select  a  menu  item  using  the  Alt  key  in  combination  with  a  let¬ 
ter  of  the  character  string.  But  once  you  put  a  bitmap  in  a  menu,  you’ve  eliminated  that  key¬ 
board  interface.  Even  if  the  bitmap  says  something,  Windows  doesn’t  know  about  it. 

This  is  where  the  WM_MENUCHAR  message  comes  in  handy.  Windows  sends  a 
WM_MENUCHAR  message  to  your  window  procedure  when  you  press  Alt  with  a  charac¬ 
ter  key  that  does  not  correspond  to  a  menu  item.  We  need  to  intercept  WM_MENUCHAR 
messages  and  check  the  value  of  wParam  (the  ASCII  character  of  the  pressed  key).  If  this 
corresponds  to  a  menu  item,  we  have  to  return  a  long  integer  back  to  Windows  where  the 
high  word  is  set  to  2  and  the  low  word  is  set  to  the  index  of  the  menu  item  we  want  associ¬ 
ated  with  that  key.  Windows  does  the  rest. 

KEYBOARD  ACCELERATORS 

Described  as  simply  as  possible,  keyboard  accelerators  are  key  combinations  that  generate 
WM_COMMAND  (or  in  some  cases  WM_SYSCOMMAND)  messages.  Most  often,  pro¬ 
grams  use  keyboard  accelerators  to  duplicate  the  action  of  common  menu  options.  (How¬ 
ever,  keyboard  accelerators  can  also  perform  nonmenu  functions.)  For  instance,  many 
Windows  programs  have  an  Edit  menu  that  includes  a  Delete  option;  these  programs  con¬ 
ventionally  assign  the  Del  key  as  a  keyboard  accelerator  for  this  option.  The  user  can  choose 
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the  Delete  option  from  the  menu  by  pressing  an  Alt-key  combination  or  can  use  the  key¬ 
board  accelerator  by  simply  pressing  the  Del  key.  When  the  window  procedure  receives  a 
WM_COMMAND  message,  it  does  not  have  to  determine  whether  the  menu  or  the  key¬ 
board  accelerator  was  used. 

Why  You  Should  Use  Keyboard  Accelerators 

You  may  ask:  Why  should  I  use  keyboard  accelerators?  Why  can’t  I  simply  trap  WM- 
_KEYDOWN  or  WM_CHAR  messages  and  duplicate  the  menu  functions  myself?  What’s 
the  advantage?  For  a  single-window  application,  you  can  certainly  trap  keyboard  messages, 
but  you  get  certain  advantages  from  using  keyboard  accelerators:  You  don’t  need  to  dupli¬ 
cate  the  menu  and  keyboard  accelerator  logic.  If  the  keyboard  accelerator  duplicates  a 
menu  function,  Windows  flashes  the  top-level  item  on  the  menu  when  a  keyboard  ac¬ 
celerator  is  used,  thus  providing  some  visual  feedback  to  the  user. 

For  applications  with  multiple  windows  and  multiple  window  procedures,  keyboard 
accelerators  become  very  important.  As  we’ve  seen,  Windows  sends  keyboard  messages  to 
the  window  procedure  for  the  window  that  currently  has  the  input  focus.  For  keyboard 
accelerators,  however,  Windows  sends  the  WM -COMMAND  message  to  the  window 
procedure  whose  handle  is  specified  in  the  Windows  function  TranslateAccelerator.  Gen¬ 
erally,  this  will  be  your  main  window,  the  same  window  that  has  the  menu,  which  means 
that  the  logic  for  acting  upon  keyboard  accelerators  does  not  have  to  be  duplicated  in  every 
window  procedure. 

This  advantage  becomes  particularly  important  if  you  use  modeless  dialog  boxes 
(discussed  in  Chapter  10)  or  child  windows  on  your  main  window’s  client  area.  If  a  particu¬ 
lar  keyboard  accelerator  is  defined  to  move  among  windows,  then  only  one  window  pro¬ 
cedure  has  to  include  this  logic.  The  child  windows  do  not  receive  WM-COMMAND 
messages  from  the  keyboard  accelerators. 

Some  Rules  on  Assigning  Accelerators 

In  theory,  you  can  define  a  keyboard  accelerator  for  almost  any  virtual  key  or  character  key 
in  combination  with  the  Shift  key,  Ctrl  key,  or  Alt  key.  However,  you  should  try  to  achieve 
some  consistency  with  other  applications  and  avoid  interfering  with  Windows’  use  of  the 
keyboard.  You  should  avoid  using  Tab,  Enter,  Esc,  and  the  Spacebar  in  keyboard  accelera¬ 
tors  because  these  are  often  used  for  system  functions. 

The  most  common  use  of  keyboard  accelerators  is  for  items  on  the  program’s  Edit 
menu.  The  recommended  keyboard  accelerators  for  these  items  have  been  changed  in 
Windows  3.1.  You  should  display  the  new  keyboard  accelerators,  but  support  both  the  old 
and  the  new,  as  shown  in  the  following  table: 
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Function 

Old  Accelerator 

New  Accelerator 

Undo 

Alt+Backspace 

Ctrl+Z 

Cut 

Shift+Del 

Ctrl+X 

Copy 

Ctrl+Ins 

Ctrl+C 

Paste 

Shift+Ins 

Ctrl+V 

Delete 

Del 

Del 

Another  common  accelerator  is  the  FI  function  key  to  invoke  help.  Avoid  use  of  the 
F4,  F5,  and  F6  keys  because  these  are  often  used  for  special  functions  in  Multiple  Docu¬ 
ment  Interface  (MDI)  programs,  which  are  discussed  in  Chapter  18. 


The  Accelerator  Table 

Keyboard  accelerator  tables  are  defined  in  your  .RC  resource  script.  The  general  form  is 
shown  here: 

MyAccelerators  ACCELERATORS 

{ 

[accelerator  definitions] 

} 

This  accelerator  table  name  is  MyAccelerators.  The  ACCELERATORS  table  does  not  include 
load  and  memory  options.  You  can  have  multiple  ACCELERATORS  tables  in  your  resource 
script. 

Each  keyboard  accelerator  you  define  requires  a  different  line  in  the  table.  There  are 
four  types  of  accelerator  definitions: 

"char”,  wID  [.NOINVERT]  [ , SHIFT]  [.CONTROL]  [.ALT] 

"Achar",  wID  [.NOINVERT]  [.SHIFT]  [.CONTROL]  [.ALT] 

nCode,  wID.  ASCII  [.NOINVERT]  [.SHIFT]  [.CONTROL]  [.ALT] 

nCode,  wID,  VIRTKEY  [ . NOINVERT]  [.SHIFT]  [.CONTROL]  [.ALT] 

In  these  examples,  "char"  means  a  single  character  enclosed  in  double  quotation  marks, 
and  "Achar"  is  the  character  A  and  a  single  character  in  double  quotation  marks.  The  wID 
number  performs  a  function  similar  to  the  menu  ID  in  a  menu  definition.  It  is  the  value  that 
Windows  sends  to  your  window  procedure  in  the  WM -COMMAND  message  to  identify 
the  accelerator.  These  are  usually  identifiers  defined  in  a  header  file.  When  the  keyboard 
accelerator  duplicates  a  menu  command,  use  the  same  ID  for  both  the  menu  and  the 
accelerator.  When  the  keyboard  accelerator  does  not  duplicate  a  menu  command,  use  a 
unique  ID. 
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Keyboard  accelerators  almost  always  select  options  in  popup  menus.  Windows  auto¬ 
matically  flashes  a  top-level  menu  item  when  you  press  an  accelerator  key  that  duplicates 
an  option  in  a  popup.  (For  example,  the  Edit  text  flashes  if  you  press  the  Del  key.)  If  you 
don’t  want  the  menu  to  flash,  include  the  option  NOINVERT. 

In  the  first  type  of  accelerator  definition,  the  keyboard  accelerator  is  a  case-sensitive 
match  of  the  character  in  double  quotes: 

"char",  wID  [ .NOINVERT]  [.SHIFT]  [.CONTROL]  [.ALT] 

If  you  want  to  define  a  keyboard  accelerator  for  that  key  in  combination  with  the  Shift  or 
Ctrl  key  or  both,  simply  add  SHIFT,  CONTROL,  or  ALT. 

In  the  second  type  of  definition,  the  keyboard  accelerator  is  the  character  in  combi¬ 
nation  with  the  Ctrl  key: 

"Achar" ,  wID  [.NOINVERT]  [.SHIFT]  [.CONTROL]  [.ALT] 

This  type  is  the  same  as  the  first  type  when  the  CONTROL  keyword  is  used  with  the  char¬ 
acter  alone. 

The  third  and  fourth  types  use  a  number  ( nCode )  rather  than  a  character  in  quotes: 

nCode,  wID,  ASCII  [ .NOINVERT]  [.SHIFT]  [.CONTROL]  [.ALT] 
nCode,  wID,  VIRTKEY  [.NOINVERT]  [.SHIFT]  [.CONTROL]  [.ALT] 

This  number  is  interpreted  as  either  a  case-sensitive  ASCII  code  or  a  virtual  key  code, 
depending  on  the  ASCII  or  VIRTKEY  keyword. 

The  most  common  keyboard  accelerators  are  the  second  and  fourth  types.  You  use 
the  second  type  for  character  keys  in  combination  with  Ctrl.  For  example,  this  defines  an 
accelerator  for  Ctrl-A: 

"AA".  wID 

Use  the  fourth  type  for  virtual  key  codes  such  as  function  keys.  This  defines  an  accelerator 
for  the  Ctrl-F9  combination: 

VK_F9 ,  wID,  VIRTKEY,  CONTROL 

The  identifier  VK_F9  is  defined  in  WINDOWS. H  as  the  virtual  key  code  for  the  F9  key,  so 
you  have  to  include  the  statement: 

//include  <windows.h> 

near  the  top  of  the  resource  script.  The  resource  compiler  defines  an  identifier  named 
RC_INVOKED  that  causes  much  of  WINDOWS.H  to  be  ignored. 

The  first  and  third  types  of  definition  shown  above  are  rarely  used.  If  you  want  to  use 
them,  watch  out  for  case-sensitivity.  Windows  does  a  case-sensitive  match  on  the  "char" 
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or  nCode  based  on  the  character  you  press.  When  you  add  the  SHIFT  keyword,  Windows 
checks  to  see  if  the  Shift  key  is  depressed.  This  situation  sometimes  causes  results  you  may 
not  anticipate.  For  instance,  if  "char"  is  "A ",  the  keyboard  accelerator  is  invoked  when  you 
press  the  A  key  with  the  Shift  key  down  or  Caps  Lock  on,  but  not  both.  If  you  use  "A"  with 
SHIFT,  the  A  key  must  be  pressed  with  Shift  down,  but  the  accelerator  can’t  be  invoked  at 
all  when  Caps  Lock  is  on.  Similarly,  "a"  by  itself  is  a  keyboard  accelerator  for  the  unshifted 
A  key  or  for  the  A  key  with  both  Shift  down  and  Caps  Lock  on.  But  "a"  with  SHIFT  invokes 
the  accelerator  only  when  Shift  is  down  and  Caps  Lock  is  on. 

When  you  define  keyboard  accelerators  for  a  menu  item,  you  should  include  the  key 
combination  in  the  menu  item  text.  The  tab  ( \/ )  character  separates  the  text  from  the  ac¬ 
celerator  so  that  the  accelerators  align  in  a  second  column.  To  notate  accelerator  keys  in  a 
menu,  use  the  text  Ctrl,  Shift,  or  Alt  followed  by  a  plus  sign  and  the  key.  For  example: 

■  F6 

■  Shift+F6 

■  Ctrl+F6 

Loading  the  Accelerator  Table 

Within  your  program,  you  use  the  Load  Accelerators  function  to  load  the  accelerator  table 
into  memory  and  obtain  a  handle  to  it.  The  Load  Accelerators  statement  is  very  similar  to 
the  LoadLcon,  LoadCursor ;  LoadBitmap ,  and  LoadMenu  statements. 

First,  define  a  handle  to  an  accelerator  table  as  type  HANDLE: 

HANDLE  hAccel  ; 

Then  load  the  accelerator  table: 

hAccel  =  LoadAccelerators  ( h Instance ,  "MyAccel erators")  ; 

As  with  icons,  cursors,  bitmaps,  and  menus,  you  can  use  a  number  for  the  accelerator  table 
name  and  then  use  that  number  in  the  LoadAccelerators  statement  with  the  MAKE- 
INTRESOURCE  macro  or  enclosed  in  quotation  marks  and  preceded  by  a  #  character. 

Translating  the  Keystrokes 

We  will  now  tamper  with  three  lines  of  code  that  are  common  to  all  the  Windows  pro¬ 
grams  that  we’ve  created  so  far  in  this  book.  The  code  is  the  standard  message  loop: 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 
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Here’s  how  we  change  it  to  use  the  keyboard  accelerator  table: 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

if  ( ITranslateAccelerator  (hwnd,  hAccel ,  &msg)) 

{ 

Transl ateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

The  Translate  Accelerator  function  determines  if  the  message  stored  in  the  msg  mes¬ 
sage  structure  is  a  keyboard  message.  If  it  is,  the  function  searches  for  a  match  in  the  ac¬ 
celerator  table  whose  handle  is  hAccel.  If  it  finds  a  match,  it  calls  the  window  procedure  for 
the  window  whose  handle  is  hwnd.  If  the  keyboard  accelerator  ID  corresponds  to  a  menu 
item  in  the  system  menu,  then  the  message  is  WM_SYSCOMMAND.  Otherwise,  the  mes¬ 
sage  is  WM-COMMAND. 

When  TranslateAccelerator  returns,  the  return  value  is  nonzero  if  the  message  has 
been  translated  (and  already  sent  to  the  window  procedure)  and  0  if  not.  If  Translate- 
Accelerator  returns  a  nonzero  value,  you  should  not  call  TranslateMessage  and  Dispatch- 
Message  but  rather  loop  back  to  the  GetMessage  call. 

The  hwnd  parameter  in  TranslateMessage  looks  a  little  out  of  place  because  it’s  not 
required  in  the  other  three  functions  in  the  message  loop.  Moreover,  the  message  structure 
itself  (the  structure  variable  msg)  has  a  member  named  hwnd ,  which  is  also  a  handle  to  a 
window. 

The  fields  of  the  msg  structure  are  filled  in  by  the  GetMessage  call.  When  the  second 
parameter  of  GetMessage  is  NULL,  the  function  retrieves  messages  for  all  windows  belong¬ 
ing  to  the  application.  When  GetMessage  returns,  the  hwnd  member  of  the  msg  structure 
is  the  window  handle  of  the  window  that  will  get  the  message.  However,  when 
TranslateAccelerator  translates  a  keyboard  message  into  a  WM -COMMAND  or 
WM-SYSCOMMAND  message,  it  replaces  the  msg.hwnd  window  handle  with  the  window 
handle  hwnd  specified  as  the  first  parameter  to  the  function.  That  is  how  Windows  sends 
all  keyboard  accelerator  messages  to  the  same  window  procedure  even  if  another  window 
in  the  application  currently  has  the  input  focus.  TranslateAccelerator  does  not  translate 
keyboard  messages  when  a  modal  dialog  box  or  message  box  has  the  input  focus,  because 
messages  for  these  windows  do  not  come  through  the  program’s  message  loop. 

In  some  cases  in  which  another  window  in  your  program  (such  as  a  modeless  dialog 
box)  has  the  input  focus,  you  may  not  want  keyboard  accelerators  to  be  translated.  You’ll 
see  how  to  handle  this  situation  in  Chapter  10. 

Receiving  the  Accelerator  Messages 

When  a  keyboard  accelerator  corresponds  to  a  menu  item  in  the  system  menu,  Translate¬ 
Accelerator  sends  the  window  procedure  a  WM_SYSCOMMAND  message.  If  you  need  to, 
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you  can  differentiate  between  a  direct  system  menu  selection  and  a  keyboard  accelerator 
for  that  system  menu  item  by  the  high  word  of  iParam. 


wParam 

LOWORD  (IParam) 

HI  WORD  (IParam) 

Accelerator: 

Accelerator  ID 

0 

1 

Menu : 

Menu  ID 

0 

0 

If  the  accelerator  ID  corresponds  to  a  menu  item  (or  does  not  correspond  to  any  item  on  the 
menu  or  system  menu),  TranslateAccelerator  sends  the  window  procedure  a  WM_COM- 
MAND  message.  The  following  table  shows  the  types  of  WM_COMMAND  messages  you 
can  receive  for  keyboard  accelerators,  menu  commands,  and  child  window  controls: 


wParam 

LOWORD  (IParam) 

HIWORD  (IParam) 

Accelerator: 

Accelerator  ID 

0 

1 

Menu: 

Menu  ID 

0 

0 

Control 

Control  ID 

Child  window  handle 

Notification  code 

If  the  keyboard  accelerator  corresponds  to  a  menu  item,  the  window  procedure  also 
receives  WM-INITMENU,  WM_INITMENUPOPUP,  and  WM -MENUSELECT  messages, 
just  as  if  the  menu  option  had  been  chosen.  Programs  usually  enable  and  disable  items  in  a 
popup  menu  when  processing  WM_INITMENUPOPUP,  so  you  still  have  that  facility  when 
using  keyboard  accelerators.  If  the  keyboard  accelerator  corresponds  to  a  disabled  or 
grayed  menu  item,  however,  TranslateAccelerator  does  not  send  the  window  procedure  a 
WM-COMMAND  or  WM-SYSCOMMAND  message. 

If  the  active  window  is  minimized,  TranslateAccelerator  sends  the  window  pro¬ 
cedure  WM-SYSCOMMAND  messages — but  not  WM-COMMAND  messages — for  key¬ 
board  accelerators  that  correspond  to  enabled  system  menu  items.  TranslateAccelerator 
also  sends  that  window  procedure  WM -COMMAND  messages  for  accelerators  that  do  not 
correspond  to  any  menu  items. 

POPPAD  with  a  Menu  and  Accelerators 

In  Chapter  6,  we  created  a  program  called  POPPAD1  that  uses  a  child  window  edit  control 
to  mimic  some  of  the  workings  of  Windows’  NOTEPAD  program.  In  this  chapter,  we’ll  add 
File  and  Edit  menus  and  call  it  POPPAD2.  The  Edit  items  will  all  be  functional;  we’ll  finish 
the  File  functions  in  Chapter  10  and  the  Print  function  in  Chapter  15.  POPPAD2  is  shown  in 
Figure  9-12  beginning  on  the  following  page. 
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POPPAD2.MAK 

# . 

#  P0PPAD2.MAK  make  file 

#  . - . 

poppad2.exe  :  poppad2.obj  poppad2.def  poppad2.res 

$(WINLINK)  poppad2,  poppad2,  NUL,  S(WINLIB),  poppad2.def 
rc  -t  poppad2.res 

poppad2.obj  :  poppad2.c  poppad2.h 
$ ( W I NCC )  poppad2.c 

poppad2.res  :  poppad2.rc  poppad2.h  poppad2.ico 
$ ( W I NRC )  poppad2. rc 


POPPAD2.C 

/* . 

P0PPAD2.C  --  Popup  Editor  Version  2  (includes  menu) 

(c)  Charles  Petzold,  1992 

*/ 


#include  <windows.h> 

#include  Mpoppad2.h" 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT.  UINT,  LONG)  ; 
char  szAppName  []  =  "PopPad2"  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HANDLE  hAccel  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 


Figure  9-1 2.  The  POPPAD2 program. 


=  CS.HREDRAW  !  CS.VREDRAW  ; 
=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 


(continued) 
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wndclass.hlcon  =  Loadlcon  (hlnstance,  szAppName)  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 

wndclass.lpszMenuName  =  szAppName  ; 

wndclass.lpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 


hwnd  =  CreateWindow  (szAppName,  szAppName, 

WS_OVERLAPP EDWIN DOW, 
GetSystemMetrics  (SM.CXSCREEN)  /  4, 
GetSystemMetrics  ( SM_CY SCREEN )  /  4, 
GetSystemMetrics  (SM_CXSCREEN)  /  2, 
GetSystemMetrics  (SM.CYSCREEN)  /  2, 
NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

hAccel  =  LoadAccelerators  (hlnstance,  szAppName)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

if  ( ITranslateAccelerator  (hwnd,  hAccel,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

return  msg.wParam  ; 

} 


AskConfirmation  (HWND  hwnd) 


{ 

return  MessageBox  (hwnd,  "Do  you  really  want  to  close  PopPad2?", 
szAppName.  MB.YESNO  !  MB_I CONQUESTION )  ; 


} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


{ 

static  HWND  hwndEdit  ; 
LONG  1  Select  ; 
WORD  wEnable  ; 


(continued) 
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switch  (message) 

{ 

case  WM_CREATE  : 

hwndEdit  =  CreateWindow  ("edit",  NULL, 

WS_CHI LD  !  WS_V I S I B LE  !  WS.HSCROLL  i  WSJ/SCROLL  ! 
WS_B0RDER  !  ES_LE FT  !  ES_MU LTI LINE  ! 
ES_AUT0HSCR0LL  !  ES_AUT0VSCR0LL, 

0 ,  0 ,  0 ,  0 , 

hwnd,  1,  ( ( LPCREATESTRUCT)  1 Param) ->hlnstance,  NULL)  ; 

return  0  ; 

case  WM_SETFOCUS  : 

SetFocus  (hwndEdit)  ; 
return  0  ; 

case  WM_SIZE  : 

MoveWindow  (hwndEdit,  0,  0,  LOWORD  (IParam), 

H I WORD  (IParam),  TRUE)  ; 

return  0  ; 

case  WM_I NITMENUPOPUP  : 
if  (IParam  ==  1) 

{ 

EnableMenuItem  (wParam,  I DM_UND0 , 

SendMessage  (hwndEdit,  EM_CANUNDO,  0,  0L)  ? 

M F_ENAB LED  :  MF_GRAYED)  ; 

EnableMenuItem  (wParam,  IDM_PASTE, 

IsCl i pboard Forma tAvai 1 abl e  ( C F_T EXT)  ? 

MF_ENABLED  :  MF_GRAYED)  ; 

lSelect  =  SendMessage  (hwndEdit,  EM.GETSEL,  0,  0L)  ; 

if  (HIWORD  (lSelect)  ==  LOWORD  (lSelect)) 
wEnable  =  MF.GRAYED  ; 

else 

wEnable  =  MF_ENAB LED  ; 

EnableMenuItem  (wParam,  IDM_CUT.  wEnable)  ; 

EnableMenuItem  (wParam,  IDM.COPY,  wEnable)  ; 

EnableMenuItem  (wParam,  IDM_DEL,  wEnable)  ; 

return  0  ; 

} 

break  ; 

case  WM.COMMAND  : 

if  (LOWORD  (IParam)) 

{ 


(continued) 


398 


Chapter  9:  Menus  and  Accelerators 


if  (wParam  ==  1  &&  HIWORD  ( 1 Param)  ==  EN_ERRSPACE) 
MessageBox  (hwnd,  "Edit  control  out  of  space.", 
szAppName,  MB_0K  !  MB.ICONSTOP)  ; 

return  0  ; 

} 

else  switch  (wParam) 

{ 

case  I DM_N EW  : 
case  IDM_0PEN  : 
case  IDM_SAVE  : 
case  I DM_SAV EAS  : 
case  I DM_PRI NT  : 

MessageBeep  (0)  ; 
return  0  ; 

case  IDM_EXIT  : 

SendMessage  (hwnd,  WM_CL0SE,  0,  0L)  ; 
return  0  ; 

case  IDMJJNDO  : 

SendMessage  (hwndEdit,  WMJJNDO,  0,  0L)  ; 
return  0  ; 

case  IDM_CUT  : 

SendMessage  (hwndEdit,  WM_CUT,  0,  0L)  ; 
return  0  ; 

case  IDM_C0PY  : 

SendMessage  (hwndEdit,  WM.COPY,  0,  0L)  ; 
return  0  ; 

case  IDM.PASTE  : 

SendMessage  (hwndEdit,  WM_PASTE,  0,  0L)  ; 
return  0  ; 

case  IDM_DEL  : 

SendMessage  (hwndEdit,  WM_C LEAR ,  0,  0L)  ; 
return  0  ; 

case  IDM.SELALL  : 

SendMessage  (hwndEdit,  EM_SETSEL,  0, 

MAKELONG  (0,  32767))  ; 

return  0  ; 
case  IDM.HELP  : 

MessageBox  (hwnd,  "Help  not  yet  implemented!", 
szAppName,  MB_0K  !  MB_I CONEXCLAMATION )  ; 
return  0  ; 


(continued) 
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case  IDM_AB0UT  : 

MessageBox  (hwnd, 

"P0PPAD2  (c)  Charles  Petzold,  1992”. 
szAppName,  MB_0K  !  MB_I CON I N FORMATION )  ; 
return  0  : 

} 

break  ; 

case  WM.CLOSE  : 

if  (IDYES  ==  AskConfi rmation  (hwnd)) 

DestroyWindow  (hwnd)  ; 
return  0  ; 

case  WM_QUERYENDSESSION  : 

if  (IDYES  ==  AskConfi rmation  (hwnd)) 
return  1L  ; 

else 

return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


POPPAD2.RC 

/* . - . - 

P0PPAD2.RC  resource  script 

. - . - . */ 

//include  <windows.h> 

//include  "poppad2.h" 

PopPad2  ICON  poppad2.ico 

PopPad2  MENU 
{ 

POPUP  ”&File” 

{ 

MENUITEM  "&New". 
MENUITEM  ”&0pen. . 
MENUITEM  "&Save”, 
MENUITEM  "Save  &As...”, 
MENUITEM  SEPARATOR 


(continued) 


IDM_NEW 
I DM_0PEN 
IDM.SAVE 
I DM_SAVEAS 
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MENUITEM  M&Print", 

MENUITEM  SEPARATOR 
MENUITEM  "E&xit", 

} 

POPUP  "&Edit" 

{ 

MENUITEM  "&Undo\tCtrl+Z'\ 
MENUITEM  SEPARATOR 
MENUITEM  "Cu&tUCtrl+X", 
MENUITEM  "&Copy\tCtrl+C", 
MENUITEM  "&Paste\tCtrl+V\ 
MENUITEM  "De&lete\tDel\ 
MENUITEM  SEPARATOR 
MENUITEM  "&Select  All", 

} 

POPUP  "&Hel p" 

{ 

MENUITEM  "&Help. . 

MENUITEM  "&About  PopPad2...", 

} 


IDM.PRINT 

IDM_EXIT 


IDM.UND0 

IDM_CUT 

IDM_C0PY 

IDM.PASTE 

IDM_DEL 

IDM.SELALL 


IDM_HELP 

IDM.ABOUT 


PopPad2  ACCELERATORS 

{ 

"AZ",  IDM_UND0 

VK_BACK,  IDM_UND0 ,  VIRTKEY,  ALT 

"AX",  IDM_CUT 

VK_DELETE,  IDM.CUT,  VIRTKEY ,  SHIFT 
,,AC",  IDM_C0PY 

VK_INSERT,  IDM_C0PY ,  VIRTKEY,  CONTROL 
"AV",  IDM_PASTE 
VK.INSERT,  IDM.PASTE,  VIRTKEY,  SHIFT 
VK_DELETE,  IDM_DEL,  VIRTKEY 
VK_F1,  IDM.HELP,  VIRTKEY 
} 


POPPAD2.H 


/* . 

POPPAD2.H  header  file 


♦define  I DM__N EW  1 
♦define  IDM.OPEN  2 
♦define  IDM.SAVE  3 
♦define  IDM_SAVEAS  4 
♦define  I DM_PRI NT  5 


(continued) 
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#define 

IDM_EXIT 

6 

#define 

IDMJJNDO 

10 

#define 

IDM_CUT 

11 

#define 

IDM_COPY 

12 

#define 

IDM.PASTE 

13 

^define 

IDM_DEL 

14 

#define 

IDM.SELALL 

15 

#define 

I DM_H  E  LP 

20 

#define 

IDM_ABOUT 

22 

POPPAD2.ICO 


POPPAD2.DEF 


P0PPAD2.DEF  nodule  definition  file 


NAME  P0PPAD2 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Popup  Editor  Version  2  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


The  POPPAD2.RC  resource  script  file  contains  the  menu  and  the  accelerator  table.  You’ll 
notice  that  the  accelerators  are  all  indicated  within  the  character  strings  of  the  Edit  popup 
menu  following  the  tab  (\t)  character. 
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Enabling  Menu  Items 

The  major  job  in  the  window  procedure  now  involves  enabling  and  graying  the  options  in 
the  Edit  menu,  which  is  done  when  processing  the  WM_INITMENUPOPUP.  First,  the  pro¬ 
gram  checks  to  see  if  the  Edit  popup  is  about  to  be  displayed.  Because  the  position  index 
of  Edit  in  the  menu  (starting  with  File  at  0)  is  1,  IParam  equals  1  if  the  Edit  popup  is  about  to 
be  displayed. 

To  determine  if  the  Undo  option  can  be  enabled,  POPPAD2  sends  an  EM -CAN- 
UNDO  message  to  the  edit  control.  The  SendMessage  call  returns  nonzero  if  the  edit  con¬ 
trol  can  perform  an  Undo  action,  in  which  case  the  option  is  enabled;  otherwise,  the 
option  is  grayed: 

EnableMenuItem  (wParam,  IDM_UND0, 

SendMessage  (hwndEdit,  EM.CANUNDO,  0,  0L)  ? 

M F_ ENABLED  :  MF_GRAYED)  ; 

The  Paste  option  should  be  enabled  only  if  the  clipboard  currently  contains  text.  We 
can  determine  this  through  the  IsClipboardFor  mat  Available  call  with  the  CF-TEXT 
identifier: 

EnableMenuItem  (wParam,  IDM_PASTE , 

IsCl i pboard Format A vai 1 abl e  (CF.TEXT)  ?  M F_ENAB LED  :  MF.GRAYED)  ; 

The  Cut,  Copy,  and  Delete  options  should  be  enabled  only  if  text  in  the  edit  control 
has  been  selected.  Sending  the  edit  control  an  EM-GETSEL  message  returns  a  long  integer 
containing  this  information: 

lSelect  =  SendMessage  (hwndEdit,  EM_GETSEL,  0,  0L)  ; 

The  low  word  of  lSelect  is  the  position  of  the  first  selected  character;  the  high  word  of 
lSelect  is  the  position  of  the  character  following  the  selection.  If  these  two  words  are  equal, 
no  text  has  been  selected: 

if  (HIWORD  (lSelect)  ==  LOWORD  (lSelect)) 
wEnable  =  M F_GRAY ED  ; 

el  se 

wEnable  =  MF.ENABLED  ; 

The  value  of  wEnable  is  then  used  for  the  Cut,  Copy,  and  Delete  options: 

EnableMenuItem  (wParam,  IDM_CUT,  wEnable)  ; 

EnableMenuItem  (wParam,  IDM_C0PY,  wEnable)  ; 

EnableMenuItem  (wParam,  IDM_DEL,  wEnable)  ; 

Processing  the  Menu  Options 

Of  course,  if  we  were  not  using  a  child  window  edit  control  for  POPPAD2,  we  would  now 
be  faced  with  the  problems  involved  with  actually  implementing  the  Undo,  Cut,  Copy, 
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Paste,  Clear,  and  Select  All  options  from  the  Edit  menu.  But  the  edit  control  makes  this  pro¬ 
cess  easy,  because  we  merely  send  the  edit  control  a  message  for  each  of  these  options: 

case  IDMJJNDO  : 

SendMessage  (hwndEdit,  WM_UND0,  0,  0L)  ; 
return  0  ; 

case  IDM.CUT  : 

SendMessage  (hwndEdit,  WM_CUT,  0,  0L)  ; 
return  0  ; 

case  IDM.COPY  : 

SendMessage  (hwndEdit,  WM_C0PY,  0,  0L)  ; 
return  0  ; 

case  IDM.PASTE  : 

SendMessage  (hwndEdit,  WM_PASTE,  0,  0L)  ; 
return  0  ; 

case  IDM_DEL  : 

SendMessage  (hwndEdit,  WM_DEL,  0,  0L)  ; 
return  0  ; 

case  IDM.SELALL  : 

SendMessage  (hwndEdit,  EM_SETSEL,  0, 

MAKELONG  (0,  32767))  ; 

return  0  ; 

Notice  that  we  could  have  simplified  this  even  further  by  making  the  values  of 
IDM-UNDO,  IDM-CUT,  and  so  forth  equal  to  the  values  of  the  corresponding  window 
messages  WM-UNDO,  WM_CUT,  and  so  forth. 

The  About  option  on  the  File  popup  invokes  a  simple  message  box: 

case  IDM-ABOUT  : 

MessageBox  (hwnd, 

"P0PPAD2  (c)  Charles  Petzold,  1992", 
szAppName,  MB_0K  !  MB_I CON  I N  FORMAT  ION)  ; 
return  0  ; 

In  Chapter  10,  we’ll  make  this  a  dialog  box.  A  message  box  is  also  invoked  when  you  select 
the  Help  option  from  this  menu  or  when  you  press  the  FI  accelerator  key. 

The  Exit  option  sends  the  window  procedure  a  WM_CLOSE  message: 

case  IDM_EXIT  : 

SendMessage  (hwnd,  WM.CLOSE,  0,  0L)  ; 
return  0  ; 

That  is  precisely  what  DefWindowProc  does  when  it  receives  a  WM-SYSCOMMAND 
message  with  tuParam  equal  to  SC -CLOSE. 

In  previous  programs,  we  have  not  processed  the  WM -CLOSE  messages  in  our  win¬ 
dow  procedure  but  have  simply  passed  them  to  DefWindowProc.  DefWindowProc  does 
something  very  simple  with  WM -CLOSE:  It  calls  the  DestroyWindow  function.  Rather  than 
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send  WM -CLOSE  messages  to  DefWindowProc,  however,  POPPAD2  processes  them.  This 
fact  is  not  so  important  now,  but  it  will  become  very  important  in  Chapter  10  when 
POPPAD  can  actually  edit  files: 

case  WM_C LOSE  : 

if  (IDYES  ==  AskConfirmation  ( hwnd ) ) 

DestroyWindow  (hwnd)  ; 
return  0  ; 


AskConfirmation  is  a  function  in  POPPAD2  that  displays  a  message  box  asking  for  confir¬ 
mation  to  close  the  program: 


AskConfirmation  (HWND  hwnd) 


{ 

return  MessageBox  (hwnd,  "Do  you  really  want  to  close  Poppad2?", 
szAppName,  MB_Y ESNO  !  MB_I CONQU ESTI ON )  ; 


} 


The  message  box  (as  well  as  the  AskConfirmation  function)  returns  IDYES  if  the  Yes  but¬ 
ton  is  selected.  Only  then  does  POPPAD2  call  DestroyWindow.  Otherwise,  the  program  is 
not  terminated. 

If  you  want  confirmation  before  terminating  a  program,  you  must  also  process  WM- 
-QUERYENDSESSION  messages.  Windows  begins  sending  every  window  procedure  a 
WM-QUERYENDSESSION  message  when  the  user  chooses  Close  from  the  MS-DOS  Ex¬ 
ecutive  system  menu.  If  any  window  procedure  returns  0  from  this  message,  the  Windows 
session  is  not  terminated.  Here’s  how  we  handle  WM_QUERYENDSESSION: 

case  WM_QUERY ENDSESS ION  : 

if  (IDYES  ==  AskConfirmation  (hwnd)) 
return  1L  ; 

else 

return  0  ; 


The  WM-CLOSE  and  WM_QUERYENDSESSION  messages  are  the  only  two  mes¬ 
sages  you  have  to  process  if  you  want  to  ask  for  user  confirmation  before  ending  a  pro¬ 
gram.  That’s  why  we  made  the  Exit  menu  option  in  POPPAD2  send  the  window  procedure 
a  WM-CLOSE  message — by  doing  so,  we  avoided  having  to  ask  for  confirmation  at  yet  a 
third  point. 

If  you  process  WM_QUERYENDSESSION  messages,  you  may  also  be  interested  in 
the  WM-ENDSESSION  message.  Windows  sends  this  message  to  every  window  procedure 
that  has  previously  received  a  WM_QUERYENDSESSION  message.  The  wParam  param¬ 
eter  is  0  if  the  session  fails  to  terminate  because  another  program  has  returned  0  from 
WM_QUERYENDSESSION.  The  WM_ENDSESSION  message  essentially  answers  the 
question:  I  told  Windows  it  was  OK  to  terminate  me,  but  did  I  really  get  terminated? 

Although  I’ve  included  the  normal  New,  Open,  Save,  and  Save  As  options  in  POP- 
PAD2’s  File  menu,  they  are  currently  nonfunctional.  To  process  these  commands,  we  need 
to  use  dialog  boxes.  You’re  now  ready  to  learn  about  them. 
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Dialog  boxes  are  most  often  used  for  obtaining  additional  input  from  the  user  beyond  what 
can  be  easily  managed  through  a  menu.  The  programmer  indicates  that  a  menu  item  in¬ 
vokes  a  dialog  box  by  adding  an  ellipsis  (...)  to  the  menu  item. 

A  dialog  box  generally  takes  the  form  of  a  popup  window  containing  various  child 
window  controls.  The  size  and  placement  of  these  controls  are  specified  in  a  “dialog  box 
template”  in  the  program’s  resource  script  file.  Windows  is  responsible  for  creating  the 
dialog  box  popup  window  and  the  child  window  controls  and  for  providing  a  window 
procedure  to  process  dialog  box  messages  (including  all  keyboard  and  mouse  input).  The 
code  within  Windows  that  does  all  this  is  sometimes  referred  to  as  the  “dialog  box 
manager.” 

Many  of  the  messages  that  are  processed  by  the  dialog  box  window  procedure  within 
Windows  are  also  passed  to  a  function  within  your  own  program,  called  a  “dialog  box  pro¬ 
cedure”  or  “dialog  procedure.”  This  function  is  similar  to  a  normal  window  procedure,  but 
with  some  important  differences.  Generally,  you  will  not  be  doing  very  much  within  the 
dialog  procedure  except  initializing  the  child  window  controls  when  the  dialog  box  is 
created,  processing  messages  from  the  child  window  controls,  and  ending  the  dialog  box. 

The  subject  of  dialog  boxes  would  normally  be  a  big  one  because  it  involves  the  use 
of  child  window  controls.  However,  we  have  already  explored  child  window  controls  in 
Chapter  6.  When  you  use  child  window  controls  in  dialog  boxes,  the  Windows  dialog  box 
manager  picks  up  many  of  the  responsibilities  that  we  assumed  in  Chapter  6.  In  particular, 
the  problems  we  encountered  with  passing  the  input  focus  between  the  scroll  bars  in  the 
COLORS1  program  do  not  occur  with  dialog  boxes.  Windows  handles  all  the  logic  neces¬ 
sary  to  shift  input  focus  between  controls  in  a  dialog  box. 
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However,  adding  a  dialog  box  to  a  program  is  not  a  trivial  undertaking.  It  involves 
changes  to  several  files — the  dialog  box  template  goes  in  the  resource  script  file,  the  dialog 
box  procedure  goes  in  the  source  code  file,  and  identifiers  used  in  the  dialog  box  often  go 
in  the  program’s  header  file.  We’ll  begin  with  a  simple  dialog  box  to  give  you  a  feel  for  the 
interconnections  between  these  various  pieces. 

MODAL  DIALOG  BOXES 

Dialog  boxes  are  either  “modal”  or  “modeless.”  The  modal  dialog  box  is  the  most  common. 
When  your  program  displays  a  modal  dialog  box,  the  user  cannot  switch  between  the  dia¬ 
log  box  and  another  window  in  your  program.  The  user  must  explicitly  end  the  dialog  box, 
usually  by  clicking  a  push  button  marked  either  OK  or  Cancel.  The  user  can,  however,  gen¬ 
erally  switch  to  another  program  while  the  dialog  box  is  still  displayed.  Some  dialog  boxes 
(called  “system  modal”)  do  not  allow  even  this.  System  modal  dialog  boxes  must  be  ended 
before  the  user  does  anything  else  in  Windows. 

Creating  an  “About”  Dialog  Box 

Even  if  a  Windows  program  requires  no  user  input,  it  will  often  have  a  dialog  box  that  is  in¬ 
voked  by  an  About  option  on  the  menu.  This  dialog  box  displays  the  name  and  icon  of  the 
program,  a  copyright  notice,  a  push  button  labeled  OK,  and  perhaps  other  information. 
The  first  program  we’ll  look  at  does  nothing  except  display  an  About  dialog  box.  The 
ABOUT1  program  is  shown  in  Figure  10-1. 

ABOUT1.MAK 

# . 

#  AB0UT1.MAK  make  file 
#- . 

aboutl.exe  :  aboutl.obj  aboutl.def  aboutl.res 

$ ( WI N LI NK )  aboutl,  aboutl,  NUL.  $(WINLIB),  aboutl 
rc  -t  aboutl.res 

aboutl.obj  :  aboutl. c  aboutl. h 
$ ( WI NCC )  aboutl. c 

aboutl.res  :  aboutl. rc  aboutl. h  aboutl. ico 
$ ( WI NRC )  aboutl. rc 


Figure  10-1.  The  ABOUT1  program. 


408 


Chapter  10:  Dialog  Boxes 


ABOUT1.C 

/* . . - . . . 

AB0UT1.C  --  About  Box  Demo  Program  No.  1 
(c)  Charles  Petzold,  1992 
. */ 

^include  <windows.h> 

#include  "aboutl.h" 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT.  LONG)  ; 

BOOL  FAR  PASCAL  .export  AboutDlgProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "Aboutl"  ; 

MSG  msg; 

HWND  hwnd  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

t 

wndclass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 
wndclass. cbClsExtra  =  0  ; 
wndclass. cbWndExtra  =  0  ; 
wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  Loadlcon  (hlnstance,  szAppName)  ; 

wndclass. hCursor  =  LoadCursor  (NULL,  IDC.ARROW)  ; 

wndclass. hbrBackground  =  GetStockObject  (WHITE.BRUSH)  ; 
wndclass. IpszMenuName  =  szAppName  ; 
wndclass. IpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "About  Box  Demo  Program", 

WS.OVERLAPP EDWIN DOW , 

CW.USEDEFAULT,  CW.USEDEFAULT, 

CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd); 

(continued) 
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while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParain  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParan) 

{ 

static  FARPROC  1 pf nAboutDl gProc  ; 
static  HANDLE  hlnstance  ; 


switch  (message) 

{ 

case  WM.CREATE  : 

hlnstance  =  ( ( LPCREATESTRUCT)  1 Param) ->hlnstance  ; 


lpfnAboutDl gProc  =  MakeProcInstance  ((FARPROC)  AboutDlgProc, 

hlnstance)  ; 


return  0  ; 


case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  IDM.AB0UT  : 

DialogBox  (hlnstance,  "AboutBox”,  hwnd, 
lpfnAboutDlgProc)  ; 

return  0  ; 

} 

break  ; 


case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  1 Param)  ; 
} 


BOOL  FAR  PASCAL  .export  AboutDlgProc  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  1 Param) 

{ 

switch  (message) 

{ 

case  WM.INITDIALOG  : 
return  TRUE  ; 


case  WM.COMMAND  : 
switch  (wParam) 
{ 


(continued) 
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case  IDOK  : 
case  IDCANCEL  : 

EndDialog  (hDlg,  0)  ; 
return  TRUE  ; 

} 

break  ; 

} 

return  FALSE  ; 

} 


ABOUT1.RC 


ABOUTl.RC  resource  script 
. */ 

#include  <windows.h> 

♦include  "aboutl.h" 

Aboutl  ICON  aboutl.ico 

Aboutl  MENU 

{ 

POPUP  "&He1 p" 

{ 

MENUITEM  "&About  Aboutl.,/’,  IDM_ABOUT 

} 

} 

AboutBox  DIALOG  20,  20,  160,  80 
STYLE  WS_POPUP  !  WS_DLGFRAME 
{ 


CTEXT  ’’Aboutl” 

■1. 

0, 

12, 

160, 

8 

ICON  ’’Aboutl” 

-1. 

8, 

8, 

0, 

0 

CTEXT  "About  Box  Demo  Program" 

-1, 

0, 

36, 

160, 

8 

CTEXT  "(c)  Charles  Petzold,  1992" 

-1, 

0. 

48, 

160, 

8 

DEFPUSHBUTTON  "OK" 

IDOK, 

64, 

60, 

32, 

14,  WS.GROUP 

} 


ABOUT1.H 


ABOUTl.H  header  file 
. . */ 

♦define  IDM_ABOUT  1 
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ABOUT1.ICO 


ABOUT1.DEF 


AB0UT1.DEF  module  definition  file 


NAME  AB0UT1 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'About  Box  Demo  No.  1  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


The  Dialog  Box  Template 

The  first  job  involved  in  adding  a  dialog  box  to  a  program  is  designing  the  dialog  box 
template.  This  template  can  go  directly  into  the  resource  script  file,  or  it  can  be  in  a  separate 
file  that  by  convention  uses  the  extension  .DLG  (for  “dialog”).  If  you  put  the  template  in  a 
separate  file,  you  include  the  line: 

rcinclude  filename. dig 
in  the  resource  script  file. 

You  can  create  the  dialog  box  template  manually  in  a  text  editor,  or  you  can  use  the 
Microsoft  Image  Editor  or  the  Borland  Resource  Toolkit.  The  output  of  these  programs  is 
not  of  publishable  quality,  so  I’ll  show  dialog  box  templates  that  look  as  if  they  were  created 
manually. 
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The  dialog  box  template  for  ABOUT1  looks  like  this: 

AboutBox  DIALOG  20,  20,  160,  80 
STYLE  WS_POPUP  !  WS.DLGFRAME 
{ 


CTEXT 

"Aboutl" 

-1, 

0. 

12, 

160, 

8 

ICON 

"Aboutl" 

-1, 

8, 

8, 

0. 

0 

CTEXT 

"About  Box  Demo  Program" 

-1, 

0, 

36, 

160, 

8 

CTEXT 

"(c)  Charles  Petzold,  1992" 

-1, 

0, 

48. 

160, 

8 

DEFPUSHBUTTON  "OK” 

IDOK, 

64, 

60, 

32, 

14,  WS.GROUP 

} 

The  first  line  gives  the  dialog  box  a  name  (in  this  case,  AboutBox).  As  is  the  case  for  other 
resources,  you  can  use  a  number  instead.  The  name  is  followed  by  the  keyword  DIALOG 
and  four  numbers.  The  first  two  numbers  are  the  je-  and  y- coordinates  of  the  upper  left  cor¬ 
ner  of  the  dialog  box,  relative  to  the  client  area  of  its  parent  when  the  dialog  box  is  invoked 
by  the  program.  The  second  two  numbers  are  the  width  and  height  of  the  dialog  box. 

These  coordinates  and  sizes  are  not  in  units  of  pixels.  They  are  instead  based  on  a 
special  coordinate  system  used  only  for  dialog  box  templates.  The  numbers  are  based  on 
the  size  of  a  system  font  character:  jc-coordinates  and  width  are  expressed  in  units  of  Va  of 
an  average  character  width;  jy-coordinates  and  height  are  expressed  in  units  of  Vs  of  the 
character  height.  Thus  for  this  particular  dialog  box,  the  upper  left  corner  of  the  dialog  box 
is  5  characters  from  the  left  edge  of  the  main  window’s  client  area  and  2Vi  characters  from 
the  top  edge.  It  is  40  characters  wide  and  10  characters  high. 

This  coordinate  system  allows  you  to  use  coordinates  and  sizes  that  will  retain  the 
general  dimensions  and  look  of  the  dialog  box  regardless  of  the  resolution  of  the  video  dis¬ 
play.  Because  system  font  characters  are  often  approximately  twice  as  high  as  they  are 
wide,  the  dimensions  of  both  the  x-axis  and  the  y- axis  are  about  the  same. 

The  function  GetDialogBaseUnits  lets  you  determine  the  system  font  sizes  that  the 
dialog  manager  uses.  For  a  standard  VGA  (perhaps  the  most  common  video  adapter  used  in 
Windows),  GetDialogBaseUnits  returns  a  character  width  of  8  and  a  character  height  of  16. 
Because  dialog  box  units  are  Va  of  the  width  of  an  average  character  and  Vs  of  the  height, 
each  dialog  box  unit  corresponds  to  2  pixels  on  a  VGA.  This  is  a  good  rule  to  remember  if 
the  idea  of  dialog  box  units  seems  too  abstract  at  times.  But  don’t  rely  on  it. 

The  DIALOG  statement  can  also  include  load  options  (PRELOAD  and  LOADON- 
CALL)  and  memory  options  (FIXED,  MOVEABLE,  and  DISCARDABLE)  immediately 
following  the  word  DIALOG.  The  defaults  are  LOADONCALL  and  MOVEABLE.  The  STYLE 
statement  in  the  template  is  similar  to  the  style  field  of  a  CreateWindow  call.  Using  WS 
-POPUP  and  WS-DLGFRAME  is  normal  for  modal  dialog  boxes,  but  we’ll  explore  some 
alternatives  later  on. 

Within  the  left  and  right  brackets,  you  define  the  child  window  controls  that  will 
appear  in  the  dialog  box.  This  dialog  box  uses  three  types  of  child  window  controls: 
CTEXT  (centered  text),  ICON  (an  icon),  and  DEFPUSHBUTTON  (a  default  push  button). 
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The  format  of  these  statements  is: 

control -type  "text"  nID,  xPos,  yPos,  xWidth,  yHeight,  dwStyle 

The  dwStyle  value  at  the  end  is  optional;  it  specifies  additional  window  styles  using  iden¬ 
tifiers  defined  in  WINDOWS.H. 

These  CTEXT,  ICON,  and  DEFPUSHBUTTON  identifiers  are  used  only  in  dialog 
boxes.  They  are  shorthand  for  a  particular  window  class  and  window  style.  For  example, 
CTEXT  indicates  that  the  class  of  the  child  window  control  is  “static”  and  that  the  style  is: 

WS.CHILD  !  SS_C ENTER  !  WS.VISIBLE  !  WS.GROUP 

Although  this  is  the  first  time  we’ve  encountered  the  WS-GROUP  identifier,  we  used 
the  WS_CHILD,  SS_CENTER,  and  WS_VISIBLE  window  styles  when  creating  static  child 
window  text  controls  in  the  COLORS1  program  in  Chapter  6. 

For  the  icon,  the  text  field  is  the  name  of  the  program’s  icon  resource,  which  is  also 
defined  in  the  ABOUT1  resource  script.  For  the  push  button,  the  text  field  is  the  text  that 
appears  inside  the  push  button.  This  text  is  equivalent  to  the  text  specified  as  the  second 
parameter  in  a  CreateWindow  c all  when  you  create  a  child  window  control  in  a  program. 

The  nID  field  is  a  value  that  the  child  window  uses  to  identify  itself  when  sending 
messages  (usually  WM_COMMMAND  messages)  to  its  parent.  The  parent  window  of  these 
child  window  controls  is  the  dialog  box  window  itself,  which  sends  these  messages  to  a 
window  procedure  in  Windows.  However,  this  window  procedure  also  sends  these  mes¬ 
sages  to  the  dialog  box  procedure  that  you’ll  include  in  your  program.  The  nID  values  are 
equivalent  to  the  child  window  IDs  used  in  the  CreateWindow  function  when  we  created 
child  windows  in  Chapter  6.  Because  the  text  and  icon  controls  do  not  send  messages  back 
to  the  parent  window,  these  values  are  set  to  -1.  The  nID  value  for  the  push  button  is  IDOK, 
which  is  defined  in  WINDOWS.H  as  1. 

The  next  four  numbers  set  the  position  of  the  child  window  control  (relative  to  the 
upper  left  corner  of  the  dialog  box’s  client  area)  and  the  size.  The  position  and  size  are  ex¬ 
pressed  in  units  of  lA  of  the  average  width  and  Ya  of  the  height  of  a  system  font  character. 
The  width  and  height  values  are  ignored  for  the  ICON  statement. 

The  DEFPUSHBUTTON  statement  in  the  dialog  box  template  includes  the  window 
style  WS_GROUP  in  addition  to  the  window  style  implied  by  the  DEFPUSHBUTTON  key¬ 
word.  I’ll  have  more  to  say  about  WS_GROUP  (and  the  related  WS-TABSTOP  style)  when 
discussing  the  second  version  of  this  program,  ABOUT2,  a  bit  later. 

The  Dialog  Box  Procedure 

The  dialog  box  procedure  within  your  program  handles  messages  to  the  dialog  box. 
Although  it  looks  very  much  like  a  window  procedure,  it  is  not  a  true  window  procedure. 
The  window  procedure  for  the  dialog  box  is  within  Windows.  That  window  procedure 
calls  your  dialog  box  procedure  with  many  of  the  messages  that  it  receives.  Here’s  the 
dialog  box  procedure  for  ABOUT1: 
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BOOL  FAR  PASCAL  .export  AboutDlgProc  (HWND  hDlg,  UINT  message, 

UINT  wParam,  LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM_I NITDIALOG  : 
return  TRUE  ; 

case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  IDOK  : 
case  IDCANCEL  : 

EndDialog  (hDlg,  0)  ; 
return  TRUE  ; 

} 

break  ; 

} 

return  FALSE  ; 

) 

The  parameters  to  this  function  are  the  same  as  those  for  a  normal  window  procedure;  as 
with  a  window  procedure,  the  dialog  box  procedure  must  be  defined: 

FAR  PASCAL  .export 

(Although  I’ve  used  hDlg  for  the  handle  to  the  dialog  box  window,  you  can  use  hwnd  instead 
if  you  like.)  Let’s  note  first  the  differences  between  this  function  and  a  window  procedure: 

■  A  window  procedure  returns  a  long;  a  dialog  box  procedure  returns  a 
BOOL  (which  is  defined  in  WINDOWS.H  as  an  inf). 

■  A  window  procedure  calls  DefWindowProc  if  it  does  not  process  a 
particular  message;  a  dialog  box  procedure  returns  TRUE  (nonzero)  if  it 
processes  a  message  and  FALSE  (0)  if  it  does  not. 

■  A  dialog  box  procedure  does  not  need  to  process  WM_PAINT  or 
WM -DESTROY  messages.  A  dialog  box  procedure  will  not  receive  a 
WM .CREATE  message;  instead,  the  dialog  box  procedure  performs 
initialization  during  the  special  WM.INITDIALOG  message. 

The  WM.INITDIALOG  message  is  the  first  message  the  dialog  box  procedure  re¬ 
ceives.  This  message  is  sent  only  to  dialog  box  procedures.  If  the  dialog  box  procedure 
returns  TRUE,  then  Windows  sets  the  input  focus  to  the  first  child  window  control  in  the 
dialog  box  that  has  a  WS.TABSTOP  style  (which  I’ll  explain  in  the  discussion  of  ABOUT2). 
In  this  dialog  box,  the  first  child  window  control  that  has  a  WS.TABSTOP  style  is  the  push 
button.  Alternatively,  during  the  processing  of  WM.INITDIALOG,  the  dialog  box  pro¬ 
cedure  can  use  SetFocus  to  set  the  focus  to  one  of  the  child  window  controls  in  the  dialog 
box  and  then  return  FALSE. 
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The  only  other  message  this  dialog  box  processes  is  WM_COMMAND.  This  is  the 
message  the  push-button  control  sends  to  its  parent  window  either  when  the  button  is 
clicked  with  the  mouse  or  when  the  Spacebar  is  pressed  while  the  button  has  the  input 
focus.  The  ID  of  the  control  (which  we  set  to  IDOK  in  the  dialog  box  template)  is  in 
wParam.  For  this  message,  the  dialog  box  procedure  calls  EndDialog ,  which  tells  Win¬ 
dows  to  destroy  the  dialog  box.  For  all  other  messages,  the  dialog  box  procedure  returns 
FALSE  to  tell  the  dialog  box  window  procedure  within  Windows  that  our  dialog  box  pro¬ 
cedure  did  not  process  the  message. 

The  messages  for  a  modal  dialog  box  don’t  go  through  your  program’s  message  queue, 
so  you  needn’t  worry  about  the  effect  of  keyboard  accelerators  within  the  dialog  box. 

Invoking  the  Dialog  Box 

During  the  processing  of  WM -CREATE  in  WndProc ,  ABOUT1  obtains  the  program’s  in¬ 
stance  handle  (and  stores  it  in  a  static  variable)  and  calls  MakeProcInstance  to  create  an 
instance  thunk  for  the  dialog  procedure.  The  pointer  to  the  instance  thunk  is  also  stored 
in  a  static  variable: 

hlnstance  =  ( ( LPCREATESTRUCT)  1 Param) ->hlnstance  ; 

lpfnAboutDlgProc  =  MakeProcInstance  ( About D1 gProc,  hlnstance)  ; 

The  MakeProcInstance  function  assures  that  AboutDlgProc  obtains  the  correct  data  seg¬ 
ment  address  for  this  instance  of  ABOUT1. 

ABOUT1  checks  for  WM.COMMAND  messages  where  wParam  is  equal  to 
IDM-ABOUT.  When  it  gets  one,  the  program  calls  DialogBox : 

DialogBox  (hlnstance,  "AboutBox",  hwnd,  lpfnAboutDlgProc)  ; 

This  function  requires  the  instance  handle  (saved  during  WM-CREATE),  the  name  of  the 
dialog  box  (as  defined  in  the  resource  script),  the  parent  of  the  dialog  box  (which  is  the 
program’s  main  window),  and  the  address  of  the  instance  thunk  returned  from  MakeProc¬ 
Instance.  If  you  use  a  number  rather  than  a  name  for  the  dialog  box  template,  you  can 
convert  it  to  a  string  using  the  MAKEINTRESOURCE  macro. 

Selecting  “About  Aboutl...”  from  the  menu  displays  the  dialog  box,  as  shown  in 
Figure  10-2.  You  can  end  this  dialog  box  by  clicking  the  OK  button  with  the  mouse,  by 
pressing  the  Spacebar,  or  by  pressing  Enter.  For  any  dialog  box  that  contains  a  default  push 
button,  Windows  sends  a  WM-COMMAND  message  to  the  dialog  box,  with  wParam  equal 
to  the  ID  of  the  default  push  button  when  Enter  or  the  Spacebar  is  pressed. 

The  DialogBox  function  you  call  to  display  the  dialog  box  will  not  return  control  to 
WndProc  until  the  dialog  box  is  ended.  The  value  returned  from  DialogBox  is  the  second 
parameter  to  the  EndDialog  function  called  within  the  dialog  box  procedure.  (This  value  is 
not  used  in  ABOUT1  but  is  used  in  ABOUT2.)  WndProc c an  then  return  control  to  Windows. 
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Program  File  Manager 
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Figure  10-2.  The  A  BOUT  1  program 's  dialog  box. 

Even  when  the  dialog  box  is  displayed,  WndProc  can  continue  to  receive  messages. 
In  fact,  you  can  send  messages  to  WndProc  from  within  the  dialog  box  procedure. 
ABOUTl’s  main  window  is  the  parent  of  the  dialog  box  popup  window,  so  the  Send- 
Message  call  in  AboutDlgProc  would  start  off  like  this: 

SendMessage  (GetParent  (hDlg),  .  .  .  )  ; 

If  you  have  a  lot  of  dialog  boxes  within  your  program,  you  may  not  want  to  create  and 
save  instance  thunks  for  all  of  them.  You  can  instead  create  instance  thunks  as  needed  and 
free  them  after  DialogBox  returns: 

lpfnDlgProc  =  MakeProcInstance  (AboutDlgProc,  hlnstance)  ; 

DialogBox  (hlnstance,  "AboutBox” ,  hwnd,  lpfnDlgProc)  ; 

FreeProcInstance  (lpfnDlgProc)  ; 

More  on  the  Dialog  Box  Style 

The  window  style  of  the  dialog  box  is  specified  in  the  STYLE  line  of  the  dialog  box  tem¬ 
plate.  For  ABOUT1,  we  used  a  style  that  is  most  common  for  modal  dialog  boxes: 

STYLE  WS.POPUP  !  WS_DLGFRAME 

However,  you  can  also  experiment  with  other  styles.  For  example,  you  can  try: 

STYLE  WS_P0PUP  !  WS.CAPTION 
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This  creates  a  dialog  box  with  a  caption  bar  and  a  normal  window  border.  The  caption  bar 
allows  the  user  to  move  the  dialog  box  around  the  display  by  using  the  mouse.  When  you 
use  WS-CAPTION,  the  x-  and  ^-coordinates  specified  in  the  DIALOG  statement  are  the 
coordinates  of  the  dialog  box’s  client  area,  relative  to  the  upper  left  corner  of  the  parent 
window’s  client  area.  The  caption  bar  will  be  shown  above  the  j-coordinate. 

If  you  have  a  caption  bar,  you  can  put  text  in  it  using  the  CAPTION  statement  in  the 
dialog  box  template: 

CAPTION  "Dialog  Box  Caption" 

following  the  STYLE  statement.  Or  while  processing  the  WM_INITDIALOG  message  in 
the  dialog  procedure,  you  can  use: 

SetWindowText  (hDlg,  "Dialog  Box  Caption")  ; 

If  you  use  the  WS_CAPTION  style,  you  can  also  add  a  system  menu  box  with  the  WS 
_SYSMENU  style: 

STYLE  WS.POPUP  !  WS.CAPTION  !  WS.SYSMENU 

This  style  allows  the  user  to  select  Move  or  Close  from  the  system  menu. 

Adding  WS_THICKFRAME  to  the  style  allows  the  user  to  resize  the  dialog  box, 
although  resizing  is  unusual  for  a  dialog  box.  If  you  don’t  mind  being  a  little  unusual,  you 
can  also  try  adding  WS_MAXIMIZEBOX  to  the  STYLE  statement. 

The  STYLE  statement  is  not  required.  If  you  do  not  include  a  STYLE  or  CAPTION 
statement  in  the  template,  the  default  style  is: 

WS.POPUP  !  WS_B0RDER 

But  this  is  rather  dull  looking.  WS_DLGFRAME  produces  much  more  attractive  results. 
If  you  include  a  CAPTION  statement  with  a  STYLE  statement,  the  default  style  is: 

WS.POPUP  !  WS.CAPTION  !  WS.SYSMENU 

You  can  also  add  a  menu  to  a  dialog  box  by  specifying: 

MENU  menu-name 

in  the  dialog  box  template.  The  argument  is  either  the  name  or  number  of  a  menu  in  the 
resource  script.  Menus  are  highly  uncommon  for  modal  dialog  boxes.  If  you  use  one,  be 
sure  that  all  the  ID  numbers  in  the  menu  and  the  dialog  box  controls  are  unique. 

The  FONT  statement  lets  you  set  something  other  than  the  system  font  for  use  with 
dialog  box  text. 

Although  the  dialog  box  window  procedure  is  normally  within  Windows,  you  can 
use  one  of  your  own  window  procedures  to  process  dialog  box  messages.  To  do  so,  you 
specify  a  window  class  name  in  the  dialog  box  template: 

CLASS  "class-name" 
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This  approach  is  rare,  but  we’ll  use  it  in  the  HEXCALC  program  shown  later  in  this  chapter. 

When  you  call  DialogBox  specifying  the  name  of  a  dialog  box  template,  Windows 
has  almost  everything  it  needs  to  create  a  popup  window  by  calling  the  normal  CreateWin- 
dow  function.  Windows  obtains  the  coordinates  and  size  of  the  window,  the  window  style, 
the  caption,  and  the  menu  from  the  dialog  box  template.  Windows  gets  the  instance  handle 
and  the  parent  window  handle  from  the  parameters  to  DialogBox.  The  only  other  piece  of 
information  it  needs  is  a  window  class  (assuming  the  dialog  box  template  does  not  specify 
one).  Windows  registers  a  special  window  class  for  dialog  boxes.  The  window  procedure 
for  this  window  class  has  access  to  the  pointer  to  your  dialog  box  procedure  (which  you 
provide  in  the  DialogBox  call),  so  it  can  keep  your  program  informed  of  messages  that  this 
popup  window  receives.  Of  course,  you  can  create  and  maintain  your  own  dialog  box  by 
creating  the  popup  window  yourself.  Using  DialogBox  is  simply  an  easier  approach. 

More  on  Defining  Controls 

In  the  dialog  box  template  in  ABOUT1.RC,  we  used  the  shorthand  notation  CTEXT,  ICON, 
and  DEFPUSHBUTTON  to  define  the  3  types  of  child  window  controls  we  wanted  in  the 
dialog  box.  There  are  10  others  you  can  use.  Each  type  implies  a  particular  predefined  win¬ 
dow  class  and  a  window  style.  The  following  table  shows  the  equivalent  window  class  and 
window  style  for  each  of  the  13  control  types: 


Control  Type 

Window  Class 

Window  Style 

PUSHBUTTON 

button 

BS-PUSHBUTTON  !  WS-TABSTOP 

DEFPUSHBUTTON 

button 

BS-DEFPUSHBUTTON  !  WS_TABSTOP 

CHECKBOX 

button 

BS-CHECKBOX  !  WS_TABSTOP 

RADIOBUTTON 

button 

BS-RADIOBUTTON  !  WS_TABSTOP 

GROUPBOX 

button 

BS_GROUPBOX  !  WS-TABSTOP 

LTEXT 

static 

SS-LEFT  !  WS-GROUP 

CTEXT 

static 

SS-CENTER  !  WS-GROUP 

RTEXT 

static 

SS-RIGHT  !  WS_GROUP 

ICON 

static 

SS-ICON 

EDITTEXT 

edit 

ES-LEFT  !  WS-BORDER  !  WS-TABSTOP 

SCROLLBAR 

scrollbar 

SBS-HORZ 

LISTBOX 

listbox 

LBS-NOTIFY  !  WS-BORDER  ! 

WS-VSCROLL 

COMBOBOX 

combobox 

CBS_SIMPLE  !  WS-TABSTOP 

The  RC  resource  compiler  is  the  only  program  that  understands  this  shorthand  notation. 
In  addition  to  the  window  styles  shown  above,  each  of  these  controls  has  the  style: 

WS.CHILD  !  WS_V I S I B LE 
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For  all  these  control  types  except  EDITTEXT,  SCROLLBAR,  LISTBOX,  and  COMBO- 
BOX,  the  format  of  the  control  statement  is: 

control -type  "text",  nID,  xPos,  yPos,  xWidth,  yHeight,  dwStyle 
For  EDITTEXT,  SCROLLBAR,  LISTBOX,  and  COMBOBOX,  the  format  is: 

control -type  nID,  xPos,  yPos,  xWidth,  yHeight,  dwStyle 

which  excludes  the  text  field.  In  both  statements,  the  dwStyle  parameter  is  optional. 

In  Chapter  6,  I  discussed  rules  for  determining  the  width  and  height  of  predefined 
child  window  controls.  You  might  want  to  refer  back  to  that  chapter  for  these  rules, 
keeping  in  mind  that  sizes  specified  in  dialog  box  templates  are  always  in  terms  of  Va  of 
the  average  character  width  and  Vs  of  the  character  height. 

The  “style”  field  of  the  control  statements  is  optional.  It  allows  you  to  include  other 
window  style  identifiers.  For  instance,  if  you  wanted  to  create  a  check  box  consisting  of 
text  to  the  left  of  a  square  box,  you  could  use: 

CHECKBOX  "text",  nID,  xPos,  yPos,  xWidth,  yHeight,  BS_LE FTTEXT 

While  the  shorthand  notation  for  child  window  controls  is  convenient,  it  is  also  in¬ 
complete.  You  can’t  create  a  child  window  edit  control  without  a  border,  for  example.  For 
this  reason,  the  RC  resource  compiler  also  recognizes  a  generalized  control  statement  that 
looks  like  this: 

CONTROL  "text",  nID,  "class",  dwStyle,  xPos,  yPos,  xWidth,  yHeight 

This  statement  allows  you  to  create  any  type  of  child  window  control  by  specifying  the 
window  class  and  the  complete  window  style.  For  example,  instead  of  using: 

PUSHBUTTON  "OK",  IDOK,  10,  20,  32,  14 
you  can  use: 

CONTROL  "OK",  IDOK,  "button",  WS.CHILD  !  WS.VISIBLE  ! 

BS.PUSHBUTTON  !  WS_TABSTOP,  10,  20,  32,  14 

When  the  resource  script  is  compiled,  these  two  statements  are  encoded  identically  in  the 
.RES  file  and  the  .EXE  file. 

When  you  use  CONTROL  statements  in  a  dialog  box  template,  you  don’t  need  to  in¬ 
clude  the  WS-CHILD  and  WS-VISIBLE  styles.  Windows  includes  these  in  the  window 
style  when  creating  the  child  windows.  The  format  of  the  CONTROL  statement  also 
clarifies  what  the  Windows  dialog  manager  does  when  it  creates  a  dialog  box.  First,  as  I 
described  earlier,  it  creates  a  popup  window  whose  parent  is  the  window  handle  that  was 
provided  in  the  DialogBox  function.  Then  for  each  control  in  the  dialog  template,  the  dia¬ 
log  box  manager  creates  a  child  window.  The  parent  of  each  of  these  controls  is  the  popup 
dialog  box.  The  CONTROL  statement  shown  above  is  translated  into  a  CreateWindow  call 
that  looks  like  this: 
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CreateWindow  ("button",  "OK", 

WS_CHI LD  !  WS_V I S I B L E  !  WS.TABSTOP  !  BS_PUSH BUTTON , 

10  *  cxChar  /  4,  20  *  cyChar  /  8, 

32  *  cxChar  /  4,  14  *  cyChar  /  8, 
hDlg,  nID,  hlnstance,  NULL)  ; 

where  cxChar  and  cyChar  are  the  width  and  height  of  a  system  font  character  in  pixels. 
The  hDlg  parameter  is  returned  from  the  CreateWindow  call  that  creates  the  dialog  box 
window.  The  hlnstance  parameter  is  obtained  from  the  original  DialogBoxc all. 

A  More  Complex  Dialog  Box 

The  simple  dialog  box  in  ABOUT1  demonstrates  the  basics  of  getting  a  dialog  box  up  and 
running;  now  let’s  try  something  a  little  more  complex.  The  ABOUT2  program,  shown  in 
Figure  10-3,  demonstrates  how  to  manage  controls  (in  this  case,  radio  buttons)  within  a 
dialog  box  procedure  and  also  how  to  paint  on  the  client  area  of  the  dialog  box. 


ABOUT2.MAK 

# . 

#  AB0UT2.MAK  make  file 

#  . 

about2.exe  :  about2.obj  about2.def  about2.res 

$(WINLINK)  about2,  about2,  NUL,  $(WINLIB) .  about2 
rc  -t  about2.res 

about2.obj  :  about2.c  about2.h 
$(WINCC)  about2.c 

about2.res  :  about2.rc  about2.h  about2.ico 
$ ( W I NRC )  about2.rc 


ABOUT2.C 


/* . - - - - 

AB0UT2.C  --  About  Box  Demo  Program  No.  2 
(c)  Charles  Petzold,  1992 
.  . . */ 


//include  <windows.h> 

//include  "about2.h" 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

BOOL  FAR  PASCAL  .export  AboutDlgProc  (HWND,  UINT,  UINT,  LONG)  ; 


Figure  10-3.  The  ABOUT2 program. 


(continued) 
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short  nCurrentColor  =  IDD_BLACK, 
nCurrentFigure  =  IDD_RECT  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "About2"  ; 

MSG  msg; 

HWND  hwnd  ; 

WN  DC  LASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. 1 pf nWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass. hbr Background 
wndcl ass . 1 pszMenuName 
wndclass.lpszClassName 


CS.HREDRAW  !  CSJ/REDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (hlnstance,  szAppName)  ; 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITE_BRUSH)  ; 
szAppName  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 

} 


hwnd  =  CreateWindow  (szAppName,  "About  Box  Demo  Program", 
WS_OVERLAPP EDWIN DOW, 

CWJJSEDEFAULT,  CW_USEDE FAU LT , 
CW_USEDEFAULT,  CW_USEDE FAU LT , 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  PaintWindow  (HWND  hwnd,  short  nColor,  short  nFigure) 

{ 

static  DWORD  dwColor  [8]  =  {  RGB  (0,  0,  0),  RGB  (  0,  0,  255), 

RGB  (0,  255,  0),  RGB  (  0,  255,  255), 

RGB  (255,  0,  0),  RGB  (255,  0,  255), 

RGB  (255,  255,  0),  RGB  (255,  255,  255)  }  ; 


(continued) 
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HBRUSH  hBrush  ; 

HDC  hdc  ; 

RECT  rect  ; 


hdc  =  GetDC  (hwnd)  ; 

GetCl ientRect  (hwnd,  &rect)  ; 

hBrush  =  CreateSol idBrush  (dwColor  [nColor  -  IDD.BLACK])  ; 
hBrush  =  SelectObject  (hdc,  hBrush)  ; 

if  (nFigure  ==  IDD.RECT) 

Rectangle  (hdc,  rect. left,  rect. top,  rect. right,  rect. bottom)  ; 

else 

Ellipse  (hdc,  rect. left,  rect. top,  rect. right,  rect. bottom)  ; 

DeleteObject  (SelectObject  (hdc,  hBrush))  ; 

ReleaseDC  (hwnd,  hdc)  ; 

} 


void  PaintTheBlock  (HWND  hCtrl ,  short  nColor,  short  nFigure) 
{ 

Inval idateRect  (hCtrl,  NULL,  TRUE)  ; 

UpdateWindow  (hCtrl )  ; 

PaintWindow  (hCtrl,  nColor,  nFigure)  ; 

} 


long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  FARPROC  1 pfnAboutDl gProc  ; 
static  HANDLE  hlnstance  ; 

PAINTSTRUCT  ps  ; 


switch  (message) 

{ 

case  WM_CREATE  : 

hlnstance  =  ( ( LPCREATESTRUCT)  1 Param) ->hlnstance  ; 


IpfnAboutDlgProc  =  MakeProcInstance  ((FARPROC)  AboutDl gProc, 

hlnstance)  ; 


return  0  ; 


case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  IDM_ABOUT  : 

if  (Dial ogBox  (hlnstance,  "AboutBox",  hwnd, 
IpfnAboutDlgProc)) 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 


break  ; 


(continued) 
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case  WM_PAI NT  : 

BeginPaint  (hwnd,  &ps)  ; 

EndPaint  (hwnd,  &ps)  ; 

PaintWindow  (hwnd,  nCurrentColor,  nCurrentFigure)  ; 
return  0  ; 

case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

BOOL  FAR  PASCAL  .export  AboutDlgProc  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HWND  hCtrlBlock  ; 
static  short  nColor,  nFigure  ; 

switch  (message) 

{ 

case  WM_I NITDIALOG  : 

nColor  =  nCurrentColor  ; 
nFigure  =  nCurrentFigure  ; 

CheckRadioButton  (hDlg,  I DD_B LACK ,  I D D_W HITE,  nColor)  ; 
CheckRadioButton  (hDlg,  IDD.RECT,  IDD.ELL,  nFigure)  ; 

hCt rl Block  =  GetDlgltem  (hDlg,  IDD.PAINT)  ; 

SetFocus  (GetDlgltem  (hDlg,  nColor))  ; 
return  FALSE  ; 

case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  IDOK  : 

nCurrentColor  =  nColor  ; 
nCurrentFigure  =  nFigure  ; 

EndDialog  (hDlg,  TRUE)  ; 
return  TRUE  ; 

case  IDCANCEL  : 

EndDialog  (hDlg,  FALSE)  ; 
return  TRUE  ; 

case  IDD.BLACK  : 
case  IDD.RED  : 
case  IDD.GREEN  : 
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case  IDD.YELLOW  : 
case  IDD.BLUE  : 
case  IDD.MAGENTA  : 
case  IDD_CYAN  : 
case  IDD_WHITE  : 

nColor  =  wParam  ; 

CheckRadioButton  (hDlg,  IDD_BLACK,  IDD_WHITE,  wParam)  ; 
PaintTheBlock  (hCtrlBlock,  nColor,  nFigure)  ; 
return  TRUE  ; 

case  IDD_RECT  : 
case  IDD_ELL  : 

nFigure  =  wParam  ; 

CheckRadioButton  (hDlg,  IDD_RECT,  IDD_ELL»  wParam)  ; 
PaintTheBlock  (hCtrlBlock,  nColor,  nFigure)  ; 
return  TRUE  ; 

} 

break  ; 

case  WM_PAI NT  : 

PaintTheBlock  (hCtrlBlock,  nColor,  nFigure)  ; 
break  ; 

} 

return  FALSE  ; 


ABOUT2.RC 


AB0UT2.RC  resource  script 

. */ 

#include  <windows.h> 

#include  "about?^” 

about2  ICON  about2.ico 

About2  MENU 
{ 

POPUP  "&Help" 

{ 

MENUITEM  "&About  About2...M,  IDM.ABOUT 

} 


#define  TABGRP  (WS.TABSTOP  !  WS_GROUP) 


(continued) 
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AboutBox  DIALOG  20,  20,  140,  188 
STYLE  WS_P0PUP  !  WS_DLGFRAME 


{ 


CTEXT 

"About2" 

-1. 

0, 

12, 

140, 

8 

ICON 

"About2" 

-1, 

8, 

8, 

0i 

0 

CTEXT 

"About  Box  Demo  Program"  -1 

i  4, 

36, 

130, 

8 

CTEXT 

it  ii 

IDD_PAINT, 

68, 

54, 

60, 

60 

GROUPBOX 

"&Col or" 

-1, 

4, 

50, 

54, 

112 

RADIOBUTTON 

"&Black" 

IDD_BLACK, 

8, 

60, 

40, 

12, 

TABGRP 

RADIOBUTTON 

"B&lue" 

IDD.BLUE, 

8, 

— i 

ro 

40, 

12 

RADIOBUTTON 

"&Green" 

I DD_GREEN , 

8, 

84. 

40, 

12 

RADIOBUTTON 

"Cya&n" 

IDD_CYAN, 

8, 

96, 

40. 

12 

RADIOBUTTON 

"&Red" 

IDD_RED, 

8. 

108, 

40, 

12 

RADIOBUTTON 

"&Magenta" 

IDD.MAGENTA, 

8, 

120, 

40, 

12 

RADIOBUTTON 

"&Yellow" 

IDD.YELLOW, 

8, 

132, 

40, 

12 

RADIOBUTTON 

"&White" 

IDD_WHITE, 

8, 

144, 

40, 

12 

GROUPBOX 

"&Figure" 

-1, 

68, 

120, 

60. 

40, 

WS.GROUP 

RADIOBUTTON 

"Rec&tangle" 

IDD_RECT, 

72, 

134, 

50, 

12, 

TABGRP 

RADIOBUTTON 

"&E1 1 i pse" 

IDD_ELL, 

72, 

146, 

50. 

12 

DEFPUSHBUTTON  "OK" 

IDOK, 

20. 

168, 

40, 

14, 

WS_GR0UP 

PUSHBUTTON 

"Cancel" 

I DCANCEL , 

80, 

168, 

40, 

14, 

WS_GR0UP 

} 


ABOUT2.H 


j  ^ _ _ _ 

AB0UT2.H  header  file 


//define 

IDM_AB0UT 

1 

//define 

I DD_B  LACK 

10 

//define 

I DD_B  LUE 

11 

//define 

IDD.GREEN 

12 

//define 

IDD.CYAN 

13 

//define 

IDD_RED 

14 

//define 

IDD.MAGENTA 

15 

//define 

I DD_Y  ELLOW 

16 

//define 

I D  D_W  HITE 

17 

//define 

IDD_RECT 

20 

//define 

IDD_ELL 

21 

//define 

I DD_PAI NT 

30 
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ABOUT2.ICO 


ABOUT2.DEF 


AB0UT2.DEF  module  definition  file 


NAME 


AB0UT2 


DESCRIPTION  ’About  Box  Demo  No.  2  (c)  Charles  Petzold,  1992’ 
EXETYPE  WINDOWS 

STUB  ’WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


The  About  box  in  ABOUT2  has  two  groups  of  radio  buttons.  One  group  is  used  to 
select  a  color,  and  the  other  group  is  used  to  select  either  a  rectangle  or  an  ellipse.  The 
rectangle  or  ellipse  is  shown  in  the  dialog  box  with  the  interior  colored  with  the  current 
color  selection.  If  you  press  the  OK  button,  the  dialog  box  is  ended,  and  the  program’s  win¬ 
dow  procedure  draws  the  selected  figure  in  its  own  client  area.  If  you  press  Cancel,  the 
client  area  of  the  main  window  remains  the  same.  The  dialog  box  is  shown  in  Figure  10-4 
on  the  following  page.  Although  the  ABOUT2  dialog  box  uses  the  predefined  identifiers 
IDOK  and  IDCANCEL  for  the  two  push  buttons,  each  of  the  radio  buttons  has  its  own  iden¬ 
tifier  beginning  with  the  letters  IDD  (“ID  for  dialog  box  control”).  These  identifiers  are 
defined  in  ABOUT2.H. 

Working  with  Dialog  Box  Controls 

In  Chapter  6,  you  discovered  that  most  child  window  controls  send  WM -COMMAND  mes¬ 
sages  to  the  parent  window.  (The  exception  is  scroll  bar  controls.)  You  also  saw  that  the 
parent  window  can  alter  child  window  controls  (for  instance,  checking  or  unchecking 
radio  buttons  or  check  boxes)  by  sending  messages  to  the  controls.  You  can  similarly  alter 
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Progd 

Manad 


Figure  10-4.  The  ABOUT2 program ’s  dialog  box. 

controls  in  a  dialog  box  procedure.  If  you  have  a  series  of  radio  buttons,  for  example,  you 
can  check  and  uncheck  the  buttons  by  sending  them  messages.  However,  Windows  also 
provides  several  shortcuts  when  working  with  controls  in  dialog  boxes.  Let’s  look  at  the 
way  in  which  the  dialog  box  procedure  and  the  child  window  controls  communicate. 

The  dialog  box  template  for  ABOUT2  is  shown  in  the  ABOUT2.RC  resource  script  in 
Figure  10-3.  The  GROUPBOX  control  is  simply  a  frame  with  a  title  (either  Color  or  Figure) 
that  surrounds  each  of  the  two  groups  of  radio  buttons.  The  eight  radio  buttons  in  the  first 
group  are  mutually  exclusive,  as  are  the  two  radio  buttons  in  the  second  group. 

When  one  of  the  radio  buttons  is  clicked  with  the  mouse  (or  when  the  Spacebar  is 
pressed  while  the  radio  button  has  the  input  focus),  the  child  window  sends  its  parent  a 
WM -COMMAND  message  with  wParam  set  to  the  ID  of  the  control.  The  low  word  of 
iParam  is  the  window  handle  of  the  control,  and  the  high  word  of  IParam  is  a  notification 
code.  For  a  radio  button,  this  notification  code  is  BN_CLICKED,  or  0.  The  dialog  box  win¬ 
dow  procedure  in  Windows  then  passes  this  WM -COMMAND  message  to  the  dialog  box 
procedure  within  ABOUT2.C.  When  the  dialog  box  procedure  receives  a  WM_COM- 
MAND  message  for  one  of  the  radio  buttons,  it  turns  on  the  check  mark  for  that  button  and 
turns  off  the  check  marks  for  all  the  other  buttons  in  the  group. 

You  might  recall  from  Chapter  6  that  checking  and  unchecking  a  button  requires  that 
you  send  the  child  window  control  a  BM-CHECK  message.  To  turn  on  a  button  check 
mark,  you  use: 

SendMessage  (hwndCtrl,  BM_S ETCH ECK ,  1,  0L)  ; 
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To  turn  off  the  check  mark,  you  use: 

SendMessage  (hwndCtrl,  BM_SETCHECK,  0,  0L)  ; 

The  hwndCtrl  parameter  is  the  window  handle  of  the  child  window  button  control. 

But  this  method  presents  a  little  problem  in  the  dialog  box  procedure,  because  you 
don’t  know  the  window  handles  of  all  the  radio  buttons.  You  know  only  the  one  from 
which  you’re  getting  the  message.  Fortunately,  Windows  provides  you  with  a  function  to 
obtain  the  window  handle  of  a  dialog  box  control  using  the  dialog  box  window  handle  and 
the  control  ID: 

hwndCtrl  =  GetDlgltem  (hDlg,  nID)  ; 

(You  can  also  obtain  the  ID  value  of  a  control  from  the  window  handle  by  using  this 
function: 

nID  =  GetWindowWord  (hwndCtrl,  GWW_ID)  ; 
but  this  is  rarely  necessary.) 

You’ll  notice  in  the  ABOUT2.H  header  file  shown  in  Figure  10-3  that  the  ID  values  for 
the  eight  colors  are  sequential  from  IDD_BLACK  to  IDD -WHITE.  This  arrangement  helps 
in  processing  the  WM-COMMAND  messages  from  the  radio  buttons.  For  a  first  attempt  at 
checking  and  unchecking  the  radio  buttons,  you  might  try  something  like  the  following  in 
the  dialog  box  procedure: 

static  short  nColor  ; 

[other program  lines] 

case  WM_COMMAND  : 
switch  (wParam) 

{ 

[other program  lines] 

case  I DD_B LACK  : 
case  IDD_RED  : 
case  IDD.GREEN  : 
case  IDD.YELLOW  : 
case  IDD.BLUE  : 
case  IDD.MAGENTA  : 
case  I DD_CY AN  : 
case  I DD_WH I TE  : 

nColor  =  wParam  ; 

for  (n  =  IDD.BLACK,  n  <=  IDD.WHITE,  n++) 

SendMessage  (GetDlgltem  (hDlg,  n), 

BM_S ETCH ECK ,  n  ==  wParam,  0L)  ; 
return  TRUE  ; 

[other program  lines] 

This  approach  works  satisfactorily.  You’ve  saved  the  new  color  value  in  nColor ;  and 
you’ve  also  set  up  a  loop  that  cycles  through  all  the  ID  values  for  the  eight  colors.  You  obtain 
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the  window  handle  of  each  of  these  eight  radio  button  controls  and  use  SendMessage  to 
send  each  handle  a  BM_SETCHECK  message.  The  wParam  value  of  this  message  is  set  to  1 
only  for  the  button  that  sent  the  WM_COMMAND  message  to  the  dialog  box  window 
procedure. 

The  first  shortcut  is  the  special  dialog  box  procedure  SendDlgltemMessage : 
SendDlgltemMessage  (hDlg,  nCtrllD,  message,  wParam,  IParam)  ; 

It  is  equivalent  to: 

SendMessage  (GetDlgltem  (hDlg,  nCtrllD),  message,  wParam,  IParam)  ; 

Now  the  loop  would  look  like  this: 

for  (n  =  I DD_B LACK ,  n  <=  I DD_WH I TE ,  n++) 

SendDlgltemMessage  (hDlg,  n,  BM_SETCHECK,  n  ==  wParam,  0L)  ; 

That’s  a  little  better.  But  the  real  breakthrough  comes  when  you  discover  the 
CheckRadioButton  function: 

CheckRadioButton  (hDlg,  nIDFirst,  nIDLast,  nIDCheck)  ; 

This  function  turns  off  the  check  marks  for  all  radio  button  controls  with  IDs  from 
nIDFirst  to  nIDLast  except  for  the  radio  button  with  an  ID  of  nIDCheck ,  which  is  checked. 
The  IDs  must  be  sequential.  So  we  can  get  rid  of  the  loop  entirely  and  use: 

CheckRadioButton  (hDlg,  I DD_B LACK ,  I D D_W HITE ,  wParam)  ; 

That’s  how  it’s  done  in  the  dialog  box  procedure  in  ABOUT2. 

A  similar  shortcut  function  is  provided  for  working  with  check  boxes.  If  you  create  a 
CHECKBOX  dialog  window  control,  you  can  turn  the  check  mark  on  and  off  using  the 
function: 

CheckDlgButton  (hDlg,  nIDCheckbox,  wCheck)  ; 

If  wCheck  is  set  to  1,  the  button  is  checked;  if  it’s  set  to  0,  the  button  is  unchecked.  You  can 
obtain  the  status  of  a  check  box  in  a  dialog  box  using: 

wCheck  =  IsDlgButtonChecked  (hDlg,  nIDCheckbox)  ; 

You  can  either  retain  the  current  status  of  the  check  mark  as  a  static  variable  within  the 
dialog  box  procedure,  or  you  can  do  something  like  this  to  toggle  the  button  on  a  WM- 
_COMMAND  message: 

CheckDlgButton  (hDlg,  nIDCheckbox, 

! IsDlgButtonChecked  (hDlg,  nIDCheckbox))  ; 

If  you  define  a  BS_AUTOCHECKBOX  control,  then  you  don’t  need  to  process  the 
WM_COMMAND  message  at  all.  You  can  simply  obtain  the  current  status  of  the  button 
using  IsDlgButtonChecked  before  terminating  the  dialog  box. 
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The  OK  and  Cancel  Buttons 

ABOUT2  has  two  push  buttons,  labeled  OK  and  Cancel.  In  the  dialog  box  template  in 
ABOUT2.RC,  the  OK  button  has  an  ID  of  IDOK  (defined  in  WINDOWS.H  as  1)  and  the 
Cancel  button  has  an  ID  of  IDCANCEL  (defined  in  WINDOWS.H  as  2).  The  OK  button  is 
the  default: 

DEFPUSHBUTTON  "OK"  IDOK,  20,  168,  40,  14,  WS_GR0UP 

PUSHBUTTON  "Cancer  IDCANCEL,  80.  168,  40,  14,  WS.GROUP 

This  arrangement  is  normal  for  OK  and  Cancel  buttons  in  dialog  boxes;  having  the 
OK  button  as  the  default  helps  out  with  the  keyboard  interface.  Here’s  how:  Normally,  you 
would  end  the  dialog  box  by  clicking  one  of  these  buttons  with  the  mouse  or  pressing  the 
Spacebar  when  the  desired  button  has  the  input  focus.  However,  the  dialog  box  window 
procedure  also  generates  a  WM -COMMAND  message  when  the  user  presses  Enter, 
regardless  of  which  control  has  the  input  focus.  The  value  of  wParam  is  set  to  the  ID  value 
of  the  default  push  button  in  the  dialog  box  unless  another  push  button  has  the  input  focus. 
In  that  case,  wParam  is  set  to  the  ID  of  the  push  button  with  the  input  focus.  If  no  push  but¬ 
ton  in  the  dialog  box  is  the  default  push  button,  then  Windows  sends  the  dialog  box  pro¬ 
cedure  a  WM-COMMAND  message  with  wParam  equal  to  IDOK.  If  the  user  presses  the 
Esc  key  or  Ctrl-Break,  Windows  sends  the  dialog  box  procedure  a  WM -COMMAND  mes¬ 
sage  with  wParam  equal  to  IDCANCEL.  So  you  don’t  have  to  add  separate  keyboard  logic  to 
the  dialog  box  procedure,  because  the  keystrokes  that  normally  terminate  a  dialog  box  are 
translated  by  Windows  into  WM_COMMAND  messages  for  these  two  push  buttons. 

The  A boutDlgProc function  handles  these  two  WM_COMMAND  messages  by  calling 
EndDialog. 

switch  (wParam) 

{ 

case  IDOK  : 

nCurrentColor  =  nColor  ; 
nCurrentFigure  =  nFigure  ; 

EndDialog  (hDlg,  TRUE)  ; 
return  TRUE  ; 

case  IDCANCEL  : 

EndDialog  (hDlg,  FALSE)  ; 
return  TRUE  ; 

ABOUT2’s  window  procedure  uses  the  global  variables  nCurrentColor  and  nCurrent¬ 
Figure  when  drawing  the  rectangle  or  ellipse  in  the  program’s  client  area.  AboutDlgProc 
uses  the  static  local  variables  nColor  and  nFigure  when  drawing  the  figure  within  the 
dialog  box. 

Notice  the  different  value  in  the  second  parameter  of  EndDialog.  This  is  the  value 
that  is  passed  back  as  the  return  value  from  the  original  DialogBox  function  in  WndProc. 
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case  IDM_AB0UT  : 

if  (Dial ogBox  (hlnstance,  "AboutBox" ,  hwnd,  lpfnAboutDlgProc)) 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

If  DialogBox  returns  TRUE  (nonzero),  meaning  that  the  OK  button  was  pressed,  then  the 
WndProc  client  area  needs  to  be  updated  with  the  new  figure  and  color.  These  were  saved 
in  the  global  variables  nCurrentColor  and  nCurrentFigure  by  AboutDlgProc  when  it 
received  a  WM_COMMAND  message  with  wParam  equal  to  IDOK.  If  DialogBox  returns 
FALSE,  the  main  window  continues  to  use  the  original  settings  of  nCurrentColor  and 
nCurrentFigure. 

TRUE  and  FALSE  are  commonly  used  in  EndDialog  calls  to  signal  to  the  main  win¬ 
dow  procedure  whether  the  user  ended  the  dialog  box  with  OK  or  Cancel.  However,  the 
parameter  to  EndDialog  is  actually  an  int,  and  DialogBox  returns  an  int,  so  it’s  possible  to 
return  more  information  in  this  way  than  simply  TRUE  or  FALSE. 

Tab  Stops  and  Groups 

In  Chapter  6,  we  used  window  subclassing  to  add  a  facility  to  COLORS1  that  let  us  move 
from  one  scroll  bar  to  another  by  pressing  the  Tab  key.  In  a  dialog  box,  window  subclassing 
is  unnecessary:  Windows  does  all  the  logic  for  moving  the  input  focus  from  one  control  to 
another.  However,  you  have  to  help  out  by  using  the  WS_TABSTOP  and  WS_GROUP  win¬ 
dow  styles  in  the  dialog  box  template.  For  all  controls  that  you  want  to  access  using  the  Tab 
key,  specify  WS_TABSTOP  in  the  window  style.  If  you  refer  back  to  the  table  on  page  419, 
you’ll  notice  that  many  of  the  controls  include  WS_TABSTOP  as  a  default,  while  others  do 
not.  Generally  the  controls  that  do  not  include  WS_TABSTOP  style  (particularly  the  static 
controls)  should  not  get  the  input  focus  because  they  can’t  do  anything  with  it.  Unless  you 
set  the  input  focus  to  a  specific  control  in  a  dialog  box  during  processing  of  the  WM-INIT- 
DIALOG  message  and  return  FALSE  from  the  message,  Windows  sets  the  input  focus  to  the 
first  control  in  the  dialog  box  that  has  the  WS_TABSTOP  style. 

The  second  keyboard  interface  that  Windows  adds  to  a  dialog  box  involves  the  cursor 
movement  keys.  This  interface  is  of  particular  importance  with  radio  buttons.  After  you  use 
the  Tab  key  to  move  to  the  currently  checked  radio  button  within  a  group,  you  need  to  use 
the  cursor  movement  keys  to  change  the  input  focus  from  that  radio  button  to  other  radio 
buttons  within  the  group.  You  accomplish  this  by  using  the  WS-GROUP  window  style.  For 
a  particular  series  of  controls  in  the  dialog  box  template,  Windows  will  use  the  cursor 
movement  keys  to  shift  the  input  focus  from  the  first  control  that  has  the  WS_GROUP  style 
up  to  (but  not  including)  the  next  control  that  has  the  WS_GROUP  style.  Windows  will 
cycle  from  the  last  control  in  a  dialog  box  to  the  first  control  if  necessary  to  find  the  end  of 
the  group. 

By  default,  the  controls  LTEXT,  CTEXT,  RTEXT,  and  ICON  include  the  WS_GROUP 
style,  which  conveniently  marks  the  end  of  a  group.  You  often  have  to  add  WS_GROUP 
styles  to  other  types  of  controls. 
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Let’s  look  at  the  dialog  box  template  in  ABOUT2.RC: 

AboutBox  DIALOG  20,  20,  140,  188 
STYLE  WS_POPUP  !  WS_D LGFRAME 
{ 


CTEXT 

"About2" 

-i. 

0, 

12, 

140, 

8 

ICON 

"About2" 

-i. 

8, 

8, 

0, 

0 

CTEXT 

"About  Box  Demo  Program"  -1, 

4, 

36, 

130, 

8 

CTEXT 

ii  ii 

I DD_PA I  NT , 

68, 

54, 

60, 

60 

GROUPBOX 

"&Color" 

-1, 

4, 

50, 

54, 

112 

RADIOBUTTON 

"&Black" 

I DD_BLACK , 

8, 

60, 

40, 

12, 

TABGRP 

RADIOBUTTON 

"B&lue" 

IDD.BLUE, 

8, 

72, 

40, 

12 

RADIOBUTTON 

"&Green" 

IDD_GREEN , 

8, 

84, 

40, 

12 

RADIOBUTTON 

"Cya&n" 

IDD_CYAN , 

8, 

96. 

40, 

12 

RADIOBUTTON 

"&Red" 

IDD_RED, 

8. 

108, 

40, 

12 

RADIOBUTTON 

"&Magenta" 

IDD.MAGENTA, 

8, 

120, 

40, 

12 

RADIOBUTTON 

"&Yel 1 ow" 

IDD.YELLOW, 

8. 

132, 

40, 

12 

RADIOBUTTON 

"&White" 

IDD_WHITE , 

8, 

144, 

40, 

12 

GROUPBOX 

"&Figure" 

-1, 

68. 

120, 

60, 

40, 

WS_GROUP 

RADIOBUTTON 

"Rec&tangl  e" 

IDD.RECT, 

72, 

134, 

50, 

12, 

TABGRP 

RADIOBUTTON 

"&E1 1 i pse" 

IDD_ELL, 

72, 

146, 

50, 

12 

DEFPUSHBUTTON  "OK" 

IDOK, 

20, 

168, 

40, 

14, 

WS.GROUP 

PUSHBUTTON 

"Cancel" 

IDCANCEL, 

80, 

168, 

40, 

14. 

WS_GROUP 

} 

To  simplify  the  appearance  of  the  template,  an  identifier  is  defined  in  ABOUT2.RC  that 
combines  WS-TABSTOP  and  WS_GROUP: 

#define  TABGRP  (WS_TABSTOP  i  WS.GROUP) 

The  four  controls  that  have  the  WS_TABSTOP  style  are  the  first  radio  buttons  of  each 
group  (explicitly  included)  and  the  two  push  buttons  (by  default).  When  you  first  invoke 
the  dialog  box,  these  are  the  four  controls  you  can  move  among  using  the  Tab  key. 

Within  each  group  of  radio  buttons,  you  use  the  cursor  movement  keys  to  change  the 
input  focus  and  the  check  mark.  For  example,  the  first  radio  button  (Black)  in  the  Color 
group  box  and  the  Figure  group  box  have  the  WS-GROUP  style.  This  means  that  you  can 
use  the  cursor  movement  keys  to  move  the  focus  from  the  Black  radio  button  up  to  (but  not 
including)  the  Figure  group  box.  Similarly,  the  first  radio  button  (Rectangle)  in  the  Figure 
group  box  and  DEFPUSHBUTTON  have  the  WS_GROUP  style,  so  you  can  use  the  cursor 
movement  keys  to  move  between  the  two  radio  buttons  in  this  group:  Rectangle  and 
Ellipse.  Both  push  buttons  get  the  WS_GROUP  style  to  prevent  the  cursor  movement  keys 
from  doing  anything  when  the  push  buttons  have  the  input  focus. 

When  using  ABOUT2,  the  dialog  box  manager  in  Windows  performs  some  magic  in 
the  two  groups  of  radio  buttons.  As  expected,  the  cursor  movement  keys  within  a  group  of 
radio  buttons  shift  the  input  focus  and  send  a  WM -COMMAND  message  to  the  dialog  box 
procedure.  But  when  you  change  the  checked  radio  button  within  the  group,  Windows 
also  assigns  the  newly  checked  radio  button  the  WS-TABSTOP  style.  The  next  time  you  tab 
to  that  group,  Windows  will  set  the  input  focus  to  the  checked  radio  button. 
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An  ampersand  (&)  in  the  text  field  causes  the  letter  that  follows  to  be  underlined  and 
adds  another  keyboard  interface.  You  can  move  the  input  focus  to  any  of  the  radio  buttons 
by  pressing  the  underlined  letter.  By  pressing  C  (for  the  Color  group  box)  or  F  (for  the 
Figure  group  box),  you  can  move  the  input  focus  to  the  currently  checked  radio  button  in 
that  group. 

Although  programmers  normally  let  the  dialog  box  manager  take  care  of  all  this, 
Windows  includes  two  functions  that  let  you  search  for  the  next  or  previous  tab  stop  or 
group  item.  These  functions  are: 

hwndCtrl  =  GetNextDl gTabltem  (hDlg,  hwndCtrl ,  bPrevious)  ; 

and: 

hwndCtrl  =  GetNextDl gGroupItem  (hDlg,  hwndCtrl,  bPrevious)  ; 

If  bPrevious  is  TRUE,  the  functions  return  the  previous  tab  stop  or  group  item;  if  FALSE, 
they  return  the  next  tab  stop  or  group  item. 

Painting  on  the  Dialog  Box 

ABOUT2  also  does  something  relatively  unusual:  It  paints  on  the  dialog  box.  Let’s  see  how 
this  works.  Within  the  dialog  box  template  in  ABOUT2.RC,  a  blank  text  control  is  defined 
with  a  position  and  size  for  the  area  we  want  to  paint: 

CTEXT  ""  I DD_PA I  NT ,  68,  54,  60,  60 

This  area  is  15  characters  wide  and  iVi  characters  high.  Because  this  control  has  no  text,  all 
that  the  window  procedure  for  the  “static”  class  does  is  erase  the  background  when  the 
child  window  control  has  to  be  repainted. 

When  the  current  color  or  figure  selection  changes  or  when  the  dialog  box  itself  gets 
a  WM _PAINT  message,  the  dialog  box  procedure  calls  PaintTheBlock, ,  which  is  a  function 
in  ABOUT2.C: 

PaintTheBlock  ( hCt r 1  Block,  nColor,  nFigure)  ; 

The  window  handle  hCtrlBlock  had  been  set  during  the  processing  of  the  WM-INIT- 
DIALOG  message: 

hCtrlBlock  =  GetDlgltem  (hDlg,  I DD_PA I  NT )  ; 

Here’s  the  PaintTheBlock  function: 

void  PaintTheBlock  (HWND  hCtrl ,  short  nColor,  short  nFigure) 

{ 

Inval idateRect  (hCtrl,  NULL,  TRUE)  ; 

UpdateWindow  (hCtrl )  ; 

PaintWindow  (hCtrl,  nColor,  nFigure)  ; 

} 
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This  invalidates  the  child  window  control,  flags  it  as  updated,  and  then  calls  another  func¬ 
tion  in  ABOUT2  called  PaintWindow. 

The  PaintWindow  function  obtains  a  device  context  handle  for  hCtrl  and  draws  the 
selected  figure,  filling  it  with  a  colored  brush  based  on  the  selected  color.  The  size  of  the 
child  window  control  is  obtained  from  GetClientRect.  Although  the  dialog  box  template 
defines  the  size  of  the  control  in  terms  of  characters,  GetClientRect  obtains  the  dimensions 
in  pixels.  You  can  also  use  the  function  MapDialogRect  to  convert  the  character  coordi¬ 
nates  in  the  dialog  box  to  pixel  coordinates  in  the  client  area. 

We’re  not  really  painting  the  dialog  box’s  client  area — we’re  actually  painting  the 
client  area  of  the  child  window  control.  Whenever  the  dialog  box  gets  a  WM-PAINT  mes¬ 
sage,  the  child  window  control  is  invalidated  and  then  updated  to  make  it  believe  that  its 
client  area  is  now  valid.  We  then  paint  on  top  of  it. 

Using  Other  Functions  with  Dialog  Boxes 

Most  functions  that  you  can  use  with  child  windows  you  can  also  use  with  controls  in  a 
dialog  box.  For  instance,  if  you’re  feeling  devious,  you  can  use  MoveWindow  to  move  the 
controls  around  the  dialog  box  and  force  the  user  to  chase  them  around  with  the  mouse. 

Sometimes  you  need  to  dynamically  enable  or  disable  certain  controls  in  a  dialog 
box,  depending  on  the  settings  of  other  controls.  This  call: 

EnableWindow  (hwndCtrl,  bEnable)  ; 

enables  the  control  when  bEnable  is  TRUE  (nonzero)  and  disables  it  when  bEnable  is 
FALSE  (0).  When  a  control  is  disabled,  it  receives  no  keyboard  or  mouse  input.  Don’t  dis¬ 
able  a  control  that  has  the  input  focus. 

Defining  Your  Own  Controls 

Although  Windows  assumes  much  of  the  responsibility  for  maintaining  the  dialog  box  and 
child  window  controls,  various  methods  let  you  slip  some  of  your  own  code  into  this  pro¬ 
cess.  We’ve  already  seen  a  method  that  allows  you  to  paint  on  the  surface  of  a  dialog  box. 
You  can  also  use  window  subclassing  (discussed  in  Chapter  6)  to  alter  the  operation  of 
child  window  controls. 

You  can  also  define  your  own  child  window  controls  and  use  them  in  a  dialog  box. 
For  example,  suppose  you  don’t  particularly  care  for  the  normal  rectangular  push  buttons 
and  would  prefer  to  create  elliptical  push  buttons.  You  can  do  this  by  registering  a  window 
class  and  using  your  own  window  procedure  to  process  messages  for  your  customized 
child  window.  You  then  specify  this  window  class  in  a  CONTROL  statement  in  the  dialog 
box  template.  The  ABOUT3  program,  shown  in  Figure  10-5  beginning  on  the  following 
page,  does  exactly  that. 
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ABOUT3.MAK 

# . 

#  AB0UT3.MAK  make  file 


about3.exe  :  about3.obj  about3.def  about3.res 

$ ( WI N LI NK)  about3,  about3,  NUL,  $(WINLIB),  about3 
rc  -t  about3.res 

about3.obj  :  about3.c  about3.h 
$ ( WI NCC )  about3.c 

about3.res  :  about3.rc  about3.h  about3.ico 
$ ( W I NRC )  about3.rc 


ABOUT3.C 

/* . 

AB0UT3.C  --  About  Box  Demo  Program  No.  3 
(c)  Charles  Petzold,  1992 
. */ 


#include  <windows.h> 
^include  "about3.h" 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

BOOL  FAR  PASCAL  .export  AboutDlgProc  (HWND,  UINT,  UINT,  LONG)  ; 
long  FAR  PASCAL  .export  El  1 ipPushWndProc  (HWND,  UINT,  UINT,  LONG) 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "About3"  ; 

MSG  msg; 

HWND  hwnd  ; 

WNDCLASS  wndclass  ; 


if  ( ihPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 


=  CS.HREDRAW  !  CS.VREDRAW  ; 
=  WndProc  ; 

=  0  ; 

=  0  ; 


Figure  10-5.  The  ABOUT3 program. 


(continued) 
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wndclass.hlnstance  =  hlnstance  ; 

wndclass.hlcon  =  Loadlcon  (hlnstance,  szAppName)  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC.ARROW)  ; 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
wndclass.lpszMenuName  =  szAppName  ; 
wndclass.lpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

wndcl ass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass.lpfnWndProc  =  EllipPushWndProc  ; 
wndclass.cbClsExtra  =  0  ; 
wndclass.cbWndExtra  =  0  ; 
wndclass.hlnstance  =  hlnstance  ; 
wndclass.hlcon  =  NULL  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARROW)  ; 

wndclass.hbrBackground  =  COLOR_WINDOW  +  1  ; 
wndclass.lpszMenuName  =  NULL  ; 
wndclass.lpszClassName  =  "EllipPush"  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "About  Box  Demo  Program", 
WS_OVERLAPPEDWI NDOW , 

CW_USEDEFAULT,  CW_US EDE FAU LT , 

CWJJSEDEFAULT,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance.  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd); 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  FARPROC  lpfnAboutDlgProc  ; 
static  HANDLE  hlnstance  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hlnstance  =  ( ( LPCREATESTRUCT)  1 Param)->hlnstance  ; 


(continued) 
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lpfnAboutDlgProc  =  MakeProcInstance  ( ( FARPROC )  AboutDl gProc, 

hlnstance)  ; 


return  0  ; 


case  WM_COMMAND  : 
switch  (wPararn) 

{ 

case  IDM_AB0UT  : 

DialogBox  (hlnstance,  "AboutBox",  hwnd, 
lpfnAboutDlgProc)  ; 

return  0  ; 

} 

break  ; 


case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
} 


BOOL  FAR  PASCAL  .export  AboutDlgProc  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM_I NITDIALOG  : 
return  TRUE  ; 


case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  IDOK  : 

EndDialog  (hDlg,  0)  ; 
return  TRUE  ; 

} 

break  ; 

} 

return  FALSE  ; 

} 

long  FAR  PASCAL  .export  El  1 i pPushWndProc  (HWND  hwnd,  UINT  message, 

UINT  wParam,  LONG  IParam) 

{ 

char  szText  [40]  ; 

HBRUSH  hBrush  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

RECT  rect  ; 


(continued) 
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switch  (message) 

{ 

case  WM_PAI NT  : 

GetClientRect  (hwnd,  &rect)  ; 

GetWindowText  (hwnd,  szText,  sizeof  szText)  ; 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

hBrush  =  CreateSol idBrush  (GetSysColor  ( COLOR_WI NDOW ) )  ; 
hBrush  =  SelectObject  (hdc,  hBrush)  ; 

SetBkColor  (hdc,  GetSysColor  ( COLOR_W I NDOW ) )  ; 

SetTextColor  (hdc,  GetSysColor  ( COLOR_W I NDOWTEXT ) )  ; 

Ellipse  (hdc,  rect.left,  rect.top,  rect. right,  rect. bottom)  ; 
DrawText  (hdc,  szText,  -1,  &rect, 

DT_SI NGLELINE  !  DT_CENTER  !  DT_VCENTER)  ; 

DeleteObject  (SelectObject  (hdc,  hBrush))  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_KEYUP  : 

if  (wParam  !=  VK_SPACE) 
break  ; 

//  fall  through 

case  WM_LBUTTONUP  : 

SendMessage  (GetParent  (hwnd),  WM_COMMAND, 

GetWindowWord  (hwnd,  GWW_ID),  (LONG)  hwnd)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


ABOUT3.RC 

/* . . . 

AB0UT3.RC  resource  script 
. . . . . */ 

//include  <windows.h> 

//include  "about3.h" 

about3  ICON  about3.ico 


(continued) 
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About3  MENU 

{ 

POPUP  "&He1p" 

{ 

MENUITEM  "&About  About3...*\  I DM_AB0UT 

} 

} 

^define  TABGRP  (WS_TABSTOP  !  WS.GROUP) 

AboutBox  DIALOG  20,  20,  160,  80 
STYLE  WS.POPUP  !  WS_DLGFRAME 
{ 


CTEXT 

"About3" 

-1, 

0,  12. 

160, 

8 

ICON 

"About3" 

-1, 

8.  8, 

0, 

0 

CTEXT 

"About  Box  Demo  Program" 

-1, 

0,  36, 

160, 

8 

CTEXT 

"(c)  Charles  Petzold,  1992" 

-1, 

0,  48, 

160, 

8 

CONTROL  "OK"  IDOK,  "EllipPush",  TABGRP,  64,  60.  32.  14 

} 


ABOUT3.H 


/* . 

AB0UT3.H  header  file 

. */ 

#def i ne  IDM_AB0UT  1 


ABOUT3.ICO 
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ABOUT3.DEF 


AB0UT3.DEF  module  definition  file 


NAME  AB0UT3 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'About  Box  Demo  No.  3  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


The  window  class  well  be  registering  is  called  “EllipPush”  (“elliptical  push  button”). 
Rather  than  use  a  DEFPUSHBUTTON  statement  in  the  dialog  box  template,  we  use  a 
CONTROL  statement  that  specifies  this  window  class: 

CONTROL  "OK”  IDOK.  "EllipPush",  TABGRP,  64,  60,  32,  14 

The  dialog  box  manager  uses  this  window  class  in  a  CreateWindow  call  when  creating  the 
child  window  control  in  the  dialog  box. 

The  ABOUT3.C  program  registers  the  “EllipPush”  window  class  in  WinMain. 


wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass. 


style 

lpfnWndProc 

cbClsExtra 

cbWndExtra 

hlnstance 

hlcon 

hCursor 

hbrBackground  = 
IpszMenuName  = 
IpszClassName  = 


CS.HREDRAW  !  CS_VREDRAW  ; 
EllipPushWndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

NULL  ; 

LoadCursor  (NULL,  IDC_ARROW) 
COLO  R_W I N  DOW  +  1  ; 

NULL  ; 

"EllipPush"  ; 


RegisterClass  (&wndclass)  ; 

The  window  class  specifies  that  the  window  procedure  is  EllipPushWndProc ,  which  is 
also  in  ABOUT3.C. 

The  EllipPushWndProc  window  procedure  processes  only  three  messages: 
WM_PAINT,  WM-KEYUP,  and  WM.LBUTTONUP.  During  the  WM.PAINT  message,  it 
obtains  the  size  of  its  window  from  GetClientRect  and  obtains  the  text  that  appears  in  the 
push  button  from  GetWindowText.  It  uses  the  Windows  functions  Ellipse  and  DrawText 
to  draw  the  ellipse  and  the  text. 
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The  processing  of  the  WM_KEYUP  and  WM_LBUTTONUP  messages  is  very  simple: 

case  WM_KEYUP  : 

if  (wParam  !=  V  ICS  PACE) 
break  ; 

//  fall  through 

case  WM_LBUTTONUP  : 

SendMessage  (GetParent  (hwnd),  WM_COMMAND, 

GetWindowWord  (hwnd,  GWW_ID),  (LONG)  hwnd)  ; 
return  0  ; 

The  window  procedure  obtains  the  handle  of  its  parent  window  (the  dialog  box)  using 
GetParent  and  sends  a  WM -COMMAND  message  with  wParam  equal  to  the  control’s  ID. 
The  ID  is  obtained  using  GetWindowWord .  The  dialog  box  window  procedure  then  passes 
this  message  on  to  the  dialog  box  procedure  within  ABOUT3.  The  result  is  a  customized 
push  button,  as  shown  in  Figure  10-6.  You  can  use  this  same  method  to  create  other  cus¬ 
tomized  controls  for  dialog  boxes. 


About  Box  Demo  Program 
(c)  Charles  Petzold,  1992 

(  OK  ) 


Figure  10-6.  A  customized  push  button  created  by  ABOUT3. 

Is  that  all  there  is  to  it?  Well,  not  really.  EllipPushWndProc  is  a  bare-bones  version  of  the 
logic  generally  involved  in  maintaining  a  child  window  control.  For  instance,  the  button 
doesn’t  flash  like  normal  push  buttons.  To  invert  the  colors  on  the  interior  of  the  push  but¬ 
ton,  the  window  procedure  would  have  to  process  WM_KEYDOWN  (from  the  Spacebar) 
and  WM_LBUTTONDOWN  messages.  The  window  procedure  should  also  capture  the 
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mouse  on  a  WM_LBUTTONDOWN  message  and  release  the  mouse  (and  return  the  button’s 
interior  color  to  normal)  if  the  mouse  is  moved  outside  the  child  window’s  client  area  while 
the  button  is  still  depressed.  Only  if  the  button  is  released  while  the  mouse  is  captured 
should  the  child  window  send  a  WM_COMMAND  message  back  to  its  parent. 

EllipPushWndProc  also  does  not  process  WM-ENABLE  messages.  As  mentioned 
above,  a  dialog  box  procedure  can  disable  a  window  using  the  EnableWindow  function. 
The  child  window  would  then  display  gray  rather  than  black  text  to  indicate  that  it  has 
been  disabled  and  cannot  receive  messages. 

If  the  window  procedure  for  a  child  window  control  needs  to  store  data  that  are 
different  for  each  created  window,  it  can  do  so  by  using  a  positive  value  of  cbWndExtra 
in  the  window  class  structure.  This  reserves  space  in  the  internal  window  structure 
that  can  be  accessed  by  using  SetWindowWord,  SetWindowLong,  GetWindowWord,  and 
GetWindowLong. 

MESSAGE  BOXES 

Let’s  take  a  breather  here.  We’ve  been  looking  at  ways  to  customize  dialog  boxes.  Now  let’s 
look  at  an  alternative  to  dialog  boxes — the  message  box.  We  began  using  message  boxes 
way  back  in  Chapter  5,  but  we  haven’t  yet  examined  them  in  detail. 

A  message  box  is  an  appropriate  and  easy-to-use  alternative  to  a  dialog  box  when 
you  need  a  simple  response  from  the  user.  The  general  syntax  is: 

n I  tern  =  MessageBox  (hwndParent,  IpszText,  IpszCaption,  nType)  ; 

The  message  box  has  a  caption  (the  character  string  IpszCaption ),  one  or  more  lines  of  text 
( IpszText ),  one  or  more  buttons,  and  (optionally)  a  predefined  icon.  One  of  the  buttons  is  a 
default.  The  nltem  value  returned  from  MessageBox  indicates  the  button  that  was  clicked. 

The  hwndParent  parameter  is  generally  the  handle  to  the  window  that  creates  the 
message  box.  The  input  focus  will  be  set  to  this  window  when  the  message  box  is 
destroyed.  If  you  don’t  have  a  window  handle  available  or  you  don’t  want  the  input  focus  to 
go  to  one  of  your  windows,  you  can  use  NULL  for  the  handle.  If  you  use  a  message  box 
within  a  dialog  box,  use  the  dialog  box  window  handle  (which  we’ve  been  calling  bDlg)  for 
this  parameter. 

The  IpszText  parameter  is  a  long  pointer  to  NULL-terminated  text  that  appears  in  the 
body  of  the  message  box.  Windows  breaks  this  text  into  several  lines  if  necessary.  You  can 
also  include  tab  characters  in  the  text,  and  you  can  define  your  own  line  breaks  using 
carriage  returns  or  linefeeds  or  both.  The  IpszCaption  string  is  generally  the  name  of 
the  application. 

The  nType  parameter  is  a  collection  of  flags  joined  by  the  C  bitwise  OR  operator.  The 
first  group  of  flags  specifies  the  push  buttons  to  appear  at  the  bottom  of  the  message  box: 
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MB_OK  (the  default),  MB_OKCANCEL,  MB.YESNO,  MB_YESNOCANCEL,  MB-RETRY- 
CANCEL,  and  MB-ABORTRETRYIGNORE.  As  you  can  see,  these  flags  allow  for  a  maxi¬ 
mum  of  three  buttons.  The  second  group  of  flags  specifies  which  of  the  buttons  is  the 
default:  MB_DEFBUTTONl  (the  default),  MB-DEFBUTTON2,  and  MB-DEFBUTTON3. 

The  third  group  of  flags  specifies  the  icon  to  appear  in  the  message  box: 
MB_ICONINFORMATION,  MB-ICONEXCLAMATION,  MB_ICONSTOP,  and  MB.ICON- 
QUESTION.  There  is  no  default.  If  you  omit  one  of  these  flags,  the  message  box  has  no 
icon.  You  should  use  the  information  icon  for  a  status  message,  the  exclamation  point  for  a 
reminder,  the  question  mark  for  a  warning  of  the  consequences  of  an  action,  and  the  stop 
icon  for  a  signal  of  serious  problems. 

The  fourth  set  of  flags  governs  whether  the  message  box  is  application  modal,  in 
which  case  the  user  can  switch  to  another  application  without  ending  the  message  box,  or 
system  modal,  which  requires  the  user  to  end  the  message  box  before  doing  anything  else. 
The  flags  are  MB_APPLMODAL  (the  default)  and  MB_SYSTEMMODAL.  Finally,  you  can 
use  a  fifth  flag,  MB_NOFOCUS,  which  displays  the  message  box  but  does  not  give  it  the 
input  focus. 

Depending  on  which  button  is  clicked,  the  message  box  returns  one  of  the  following 
identifiers:  IDOK,  IDCANCEL,  IDYES,  IDNO,  IDRETRY,  and  IDABORT. 

Popup  Information 

One  handy  use  of  a  message  box  during  program  development  is  to  provide  information  to 
you  while  the  program  is  executing.  It  would  be  ideal  if  you  could  use  a  message  box  much 
as  you  use  print/ in  C  programs  for  MS-DOS,  with  a  formatting  string  and  a  variable  num¬ 
ber  of  arguments.  And  in  fact,  you  can  create  a  function  that  lets  you  do  this: 

void  OkMsgBox  (char  *szCaption,  char  *szFormat,  ...) 

{ 

char  szBuffer  [256]  ; 
char  *pArguments  ; 

pArguments  =  (char  *)  &szFormat  +  sizeof  szFormat  ; 
vsprintf  (szBuffer,  szFormat,  pArguments)  ; 

MessageBox  (NULL,  szBuffer,  szCaption,  MB_0K)  ; 

} 

The  vsprintf  function  is  similar  to  sprint/  except  that  it  uses  a  pointer  to  a  series  of  argu¬ 
ments  ( pArguments )  rather  than  the  arguments  themselves.  OkMsgBox  sets  pArguments 
to  the  arguments  on  the  stack  when  OkMsgBox  is  called.  The  first  parameter  to  OkMsgBox 
is  the  message  box  caption,  the  second  parameter  is  a  format  string,  and  the  third  and 
subsequent  parameters  are  the  values  to  be  displayed.  Let’s  say  you  want  a  message  box  to 
appear  every  time  the  window  procedure  gets  a  WM-SIZE  message.  Your  code  might  look 
like  this: 
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case  WM.SIZE  : 

OkMsgBox  ("WM.SIZE  Message". 

"wParam  =  %04X,  lParam  =  %04X-%04X". 
wParam,  HIWORD  (lParam),  LOWORD  (lParam))  ; 

[other program  lines] 
return  0  ; 

This  displays  the  values  of  wParam  and  lParam  within  the  message  box. 

MODELESS  DIALOG  BOXES 

At  the  beginning  of  this  chapter,  I  explained  that  dialog  boxes  can  be  either  “modal”  or 
“modeless.”  So  far  we’ve  been  looking  at  modal  dialog  boxes,  the  more  common  of  the  two 
types.  Modal  dialog  boxes  (except  system  modal  dialog  boxes)  allow  the  user  to  switch 
between  the  dialog  box  and  other  programs.  However,  the  user  cannot  switch  to  another 
window  in  the  program  until  the  modal  dialog  box  is  destroyed.  Modeless  dialog  boxes 
allow  the  user  to  switch  between  the  dialog  box  and  the  window  that  created  it  as  well  as 
between  the  dialog  box  and  other  programs.  The  modeless  dialog  box  is  thus  more  akin  to 
the  regular  popup  windows  that  your  program  might  create. 

Modeless  dialog  boxes  are  preferred  when  the  user  would  find  it  convenient  to  keep 
the  dialog  box  displayed  for  a  while.  For  instance,  the  Windows  WRITE  program  uses 
modeless  dialog  boxes  for  the  Find  and  Change  dialogs.  If  the  Find  dialog  box  were  modal, 
the  user  would  have  to  choose  Find  from  the  menu,  enter  the  string  to  be  found,  end  the 
dialog  box  to  return  to  the  document,  and  then  repeat  the  entire  process  to  search  for  an¬ 
other  occurrence  of  the  same  string.  Allowing  the  user  to  switch  between  the  document 
and  the  dialog  box  is  much  more  convenient. 

As  you’ve  seen,  modal  dialog  boxes  are  created  using  DialogBox.  The  function 
returns  a  value  only  after  the  dialog  box  is  destroyed.  It  returns  the  value  specified  in  the 
second  parameter  of  the  EndDialog  call  that  was  used  within  the  dialog  box  procedure  to 
terminate  the  dialog  box.  Modeless  dialog  boxes  are  created  using  CreateDialog.  This 
function  takes  the  same  parameters  as  DialogBox : 

hDlgModeless  =  CreateDialog  (hlnstance,  1 pszTempl ate.  hwndParent, 

1 pfnDi al ogProc)  ; 

The  difference  is  that  the  CreateDialog  function  returns  immediately  with  the  window 
handle  of  the  dialog  box.  Normally,  you  store  this  window  handle  in  a  global  variable. 

Although  the  use  of  the  names  DialogBox  with  modal  dialog  boxes  and  CreateDialog 
with  modeless  dialog  boxes  may  seem  arbitrary,  you  can  remember  which  is  which  by 
keeping  in  mind  that  modeless  dialog  boxes  are  similar  to  normal  windows.  CreateDialog 
should  remind  you  of  the  CreateWindow  function,  which  creates  normal  windows. 
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Differences  Between  Modal  and  Modeless  Dialog  Boxes 

Working  with  modeless  dialog  boxes  is  similar  to  working  with  modal  dialog  boxes,  but 
there  are  several  important  differences: 

■  Modeless  dialog  boxes  usually  include  a  caption  bar  and  a  system  menu 
box.  The  STYLE  statement  in  the  dialog  box  template  for  a  modeless 
dialog  box  will  look  something  like  this: 

STYLE  WS_P0PUP  !  WS.CAPTION  !  WS.SYSMENU  !  WS.VISIBLE 

The  caption  bar  and  system  menu  allow  the  user  to  move  the  modeless 
dialog  box  to  another  area  of  the  display  using  either  the  mouse  or  the 
keyboard.  You  don’t  normally  provide  a  caption  bar  and  system  menu 
with  a  modal  dialog  box,  because  the  user  can’t  do  anything  in  the  under¬ 
lying  window  anyway. 

■  Notice  that  the  WS -VISIBLE  style  is  included  in  our  sample  STYLE 
statement.  If  you  omit  WS-VISIBLE,  you  must  call  ShowWindow  after  the 
CreateDialog  call: 

hDl gModel ess  =  CreateDialog  (  ...  )  ; 

ShowWindow  (hDl gModel ess ,  SW.SHOW)  ; 

If  you  neither  include  WS_VISIBLE  nor  call  ShowWindow ,  the  modeless 
dialog  box  will  not  be  displayed.  In  overlooking  this  fact,  programmers 
who  have  mastered  modal  dialog  boxes  often  experience  difficulties 
when  they  first  try  to  create  a  modeless  dialog  box. 

■  Unlike  messages  to  modal  dialog  boxes  and  message  boxes,  messages  to 
modeless  dialog  boxes  come  through  your  program’s  message  queue.  The 
message  queue  must  be  altered  to  pass  these  messages  to  the  dialog  box 
window  procedure.  Here’s  how  you  do  it:  When  you  use  CreateDialog  to 
create  a  modeless  dialog  box,  you  should  save  the  dialog  box  handle 
returned  from  the  call  in  a  global  variable  (for  instance,  hDlgModeless). 

Change  your  message  loop  to  look  like  this: 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

if  (hDlgModeless  ==  0  ! !  ! IsDi al ogMessage  (hDlgModeless,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

If  the  message  is  intended  for  the  modeless  dialog  box,  then 
IsDialogMessage  sends  it  to  the  dialog  box  window  procedure  and  returns 
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TRUE  (nonzero);  otherwise,  it  returns  FALSE  (0).  The  TranslateMessage 
and  Dispatch  Message  functions  should  be  called  only  if  hDlgModeless  is  0 
or  if  the  message  is  not  for  the  dialog  box.  If  you  use  keyboard  accelerators 
for  your  program’s  window,  then  the  message  loop  looks  like  this: 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

if  (hDlgModeless  ==  0  ! :  ! IsDi al ogMessage  (hDlgModeless,  &msg)) 

{ 

if  ( ITranslateAccelerator  (hwnd,  hAccel ,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

} 

Because  global  variables  are  initialized  to  0,  hDlgModeless  will  be  0  until 
the  dialog  box  is  created,  thus  ensuring  that  IsDialogMessage  is  not  called 
with  an  invalid  window  handle.  You  must  take  the  same  precaution  when 
you  destroy  the  modeless  dialog  box  as  explained  below. 

The  hDlgModeless  variable  can  also  be  used  by  other  parts  of  the 
program  as  a  test  of  the  existence  of  the  modeless  dialog  box.  For 
example,  other  windows  in  the  program  can  send  messages  to  the  dialog 
box  while  hDlgModeless  is  not  equal  to  0. 

■  Use  DestroyWindow  rather  than  EndDialog  to  end  a  modeless  dialog  box. 

When  you  call  DestroyWindow ,  set  the  hDlgModeless  global  variable  to  0. 

The  user  customarily  terminates  a  modeless  dialog  box  by  choosing  Close  from  the 
system  menu.  Although  the  Close  option  is  enabled,  the  dialog  box  window  procedure 
within  Windows  does  not  process  the  WM -CLOSE  message.  You  must  do  this  yourself  in 
the  dialog  box  procedure: 

case  WM_C LOSE  : 

DestroyWindow  (hDlg)  ; 
hDlgModeless  =  0  ; 
break  ; 

Note  the  difference  between  these  two  window  handles:  The  hDlg  parameter  to  Destroy¬ 
Window  is  the  parameter  passed  to  the  dialog  box  procedure;  hDlgModeless  is  the  global 
variable  returned  from  CreateDialog  that  you  test  within  the  message  loop. 

You  can  also  allow  a  user  to  close  a  modeless  dialog  box  using  push  buttons.  Use  the 
same  logic  as  for  the  WM -CLOSE  message.  Any  information  that  the  dialog  box  must 
“return”  to  the  window  that  created  it  can  be  stored  in  global  variables. 
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The  New  COLORS  Program 

The  COLORS1  program  described  in  Chapter  6  created  nine  child  windows  to  display  three 
scroll  bars  and  six  text  items.  At  that  time,  the  program  was  one  of  the  more  complex  we 
had  developed.  Converting  COLORS1  to  use  a  modeless  dialog  box  makes  the  program — 
and  particularly  its  WndProc  function — almost  ridiculously  simple.  The  revised  COLORS2 
program  is  shown  in  Figure  10-7. 


COLORS2.MAK 

# . . 

//  C0L0RS2.MAK  make  file 
# . - . 

colors2.exe  :  colors2.obj  colors2.def  colors2.res 

$(WINLINK)  colors2,  colors2,  NUL,  $(WINLIB),  colors2 
rc  -t  colors2.res 

colors2.obj  :  colors2.c 
S(WINCC)  col ors2.c 

colors2.res  :  colors2.rc 
$ ( W I N RC )  col ors2 . rc 


COLORS2.C 


/* 


C0L0RS2.C  --  Version  using  Modeless  Dialog  Box 
(c)  Charles  Petzold,  1992 


*/ 


//include  <windows.h> 

//define  min(a,b)  (((a)  <  (b) )  ?  (a)  :  (b)) 
//define  max(a,b)  (((a)  >  (b))  ?  (a)  :  (b)) 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

BOOL  FAR  PASCAL  .export  ColorScrDlg  (HWND,  UINT,  UINT,  LONG)  ; 

HWND  hDlgModeless  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCndLine,  int  nCmdShow) 


{ 


Figure  10-7.  The  COLORS2 program. 


(continued) 
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static  char  szAppName[]  =  "Colors2"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  (hPrevInstance) 
return  FALSE  ; 

wndclass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

wndclass. cbWndExtra  =  0  ; 

wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  NULL  ; 

wndclass. hCursor  =  LoadCursor  (NULL,  IDC.ARROW)  ; 

wndclass. hbrBackground  =  CreateSolidBrush  (0L)  ; 
wndclass. IpszMenuName  =  NULL  ; 
wndclass. IpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

hwnd  =  CreateWindow  (szAppName,  "Color  Scroll", 

WS.OVERLAPPEDWINDOW  !  WS_CLI PCHI LDREN , 

CWJJSEDEFAULT,  CWJJSEDEFAULT, 

CWJJSEDEFAULT,  CW_USEDE FAU LT , 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

hDlgModeless  =  CreateDialog  (hlnstance,  "ColorScrDlg",  hwnd, 

MakeProcInstance  ( ( FARPROC)  ColorScrDlg,  hlnstance))  ; 

while  (GetMessage  (&msg,  NULL.  0,  0)) 

{ 

if  (hDlgModeless  ==  0  ! !  ! IsDi al ogMessage  (hDlgModeless,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 


(continued) 
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case  WM_DESTROY  : 

DeleteObject  (SetCl assWord  (hwnd,  GCW.HBRBACKGROUND, 
GetStockObject  (WHITE_BRUSH) ) )  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

BOOL  FAR  PASCAL  .export  ColorScrDlg  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  short  color  [3]  ; 

HWND  hwndParent,  hCtrl  ; 

short  nCtrllD,  nlndex  ; 

switch  (message) 

{ 

case  WM_I NITDIALOG  : 

for  (nCtrllD  =  10  ;  nCtrllD  <  13  ;  nCtrlID++) 

{ 

hCtrl  =  GetDlgltem  (hDlg,  nCtrllD)  ; 

SetScroll Range  (hCtrl,  SB.CTL,  0,  255,  FALSE)  ; 
SetScrol 1 Pos  (hCtrl,  SB.CTL,  0,  FALSE)  ; 

} 

return  TRUE  ; 

case  WM.VSCROLL  : 

hCtrl  =  HIWORD  (IParam)  ; 

nCtrllD  =  GetWindowWord  (hCtrl,  GWW.ID)  ; 

nlndex  =  nCtrl ID  -  10  ; 

hwndParent  =  GetParent  (hDlg)  ; 

switch  (wParam) 

{ 

case  SB.PAGEDOWN  : 

color  [nlndex]  +=  15  ;  //  fall  through 

case  SB_LI NEDOWN  : 

color  [nlndex]  =  min  (255,  color  [nlndex]  +  1)  ; 
break  ; 

case  SB.PAGEUP  : 

color  [nlndex]  -=  15  ;  //  fall  through 

case  SB.LINEUP  : 

color  [nlndex]  =  max  (0,  color  [nlndex]  -  1)  ; 
break  ; 
case  SB.TOP  : 

color  [nlndex]  =  0  ; 
break  ; 


(continued) 


450 


Chapter  10:  Dialog  Boxes 


case  SB_B0TT0M  : 

color  [nlndex]  =  255  ; 
break  ; 

case  SB_THUMBPOS ITION  : 
case  SB.THUMBTRACK  : 

color  [nlndex]  =  LOWORD  (IParam)  ; 
break  ; 
default  : 

return  FALSE  ; 

} 

SetScrollPos  (hCtrl,  SB.CTL,  color  [nlndex],  TRUE.)  ; 
SetDlgltemlnt  (hDlg,  nCtrllD  +  3,  color  [nlndex],  FALSE)  ; 

DeleteObject  ( 

SetClassWord  (hwnd,  GCW_HBRBACKGROUND, 

CreateSol idBrush  ( 

RGB  (color[0],  col  or [1] ,  color[2]))))  ; 

InvalidateRect  (hwndParent,  NULL,  TRUE)  ; 
return  TRUE  ; 

} 

return  FALSE  ; 


COLORS2.RC 


/* . . . 

C0L0RS2.RC  resource  script 
. */ 


♦include  <wi ndows.fi> 

♦define  SBS_VERT_TAB  (SBS.VERT  !  WS_TABSTOP) 

ColorScrDlg  DIALOG  8.  16,  124,  132 

STYLE  WS.POPUP  !  WS.CAPTION  !  WS_SYSMENU  i  WS.VISIBLE 


CAPTION  "Color 
{ 

CONTROL  ”&Red", 

Scroll 

Scrollbars” 

■1. 

"static”. 

SS_CENTER,  10, 

4, 

24, 

8 

CONTROL 

10, 

"scrollbar", 

SBS_VERT_TAB ,  10, 

16, 

24, 

100 

CONTROL  ”0”, 

13. 

"static". 

SS.CENTER,  10, 

120, 

24, 

8 

CONTROL  "&Green 

",  -1, 

"static". 

SS_CENTER,  50, 

4, 

24, 

8 

CONTROL 

11, 

"scrollbar", 

SBS_VERT_TAB,  50. 

16, 

24, 

100 

CONTROL  "0", 

14, 

"static", 

SS.CENTER,  50, 

120, 

24, 

8 

CONTROL  "&Blue" 

,  -1, 

"static". 

SS.CENTER,  90, 

4, 

24, 

8 

CONTROL 

12, 

"scrollbar", 

SBS.VERT.TAB,  90, 

16, 

24, 

100 

CONTROL  "0", 

15, 

"static", 

SS.CENTER.  90. 

120, 

24, 

8 

} 
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COLORS2.DEF 


C0L0RS2.DEF  module  definition  file 


NAME 


C0L0RS2 


DESCRIPTION  'Color  Scroll  with  Dialog  Box  (c)  Charles  Petzold,  1992' 
EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


Although  the  original  COLORS1  program  displayed  scroll  bars  that  were  based  on  the 
size  of  the  window,  the  new  version  keeps  them  at  a  constant  size  within  the  modeless 
dialog  box,  as  shown  in  Figure  10-8.  The  dialog  box  template  in  COLORS2.RC  uses 
CONTROL  statements  for  all  nine  child  windows  in  the  dialog  box.  The  modeless  dialog 
box  is  created  in  COLORS2’s  WinMain  function  following  the  ShowWindow  call  for  the 
program’s  main  window.  Note  that  the  window  style  for  the  main  window  includes 
WS_CLIPCHILDREN,  which  allows  the  program  to  repaint  the  main  window  without  eras¬ 
ing  the  dialog  box. 


Figure  10-8.  The  COLORS2  display. 
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The  dialog  box  window  handle  returned  from  CreateDialog  is  stored  in  the  global 
variable  hDlgModeless  and  tested  during  the  message  loop,  as  described  above.  In  this  pro¬ 
gram,  however,  it  isn’t  necessary  to  store  the  handle  in  a  global  variable  or  to  test  the  value 
before  calling  IsDialogMessage.  The  message  loop  could  have  been  written  like  this: 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

if  (! IsDialogMessage  (hDlgModeless,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  ( &msg )  ; 

} 

} 

Because  the  dialog  box  is  created  before  the  program  enters  the  message  loop  and  the 
dialog  box  is  not  destroyed  until  the  program  terminates,  the  value  of  hDlgModeless  will 
always  be  valid.  I  included  the  logic  in  case  you  want  to  add  some  code  to  the  dialog  box 
window  procedure  to  destroy  the  dialog  box: 

case  WM_C LOSE  : 

DestroyWindow  (hDlg)  ; 
hDlgModeless  =  0  ; 
break  ; 

In  the  original  COLORS1  program,  SetWindowText  set  the  values  of  the  three 
numeric  labels  after  converting  the  integers  to  text  with  itoa.  The  code  looked  like  this: 

SetWindowText  (hwndVal ue[n] ,  itoa  ( col or[n] .  szBuffer,  10))  ; 

The  value  of  n  was  the  ID  number  of  the  current  scroll  bar  being  processed,  and  hChValue 
was  an  array  containing  the  window  handles  of  the  three  static  text  child  windows  for  the 
numeric  values  of  the  colors. 

The  new  version  uses  SetDlgltemlnt  to  set  each  text  field  of  each  child  window  to  a 
number: 

SetDlgltemlnt  (hDlg,  nCtrllD  +  3,  color  [nCtrllD],  FALSE)  ; 

(Although  SetDlgltemlnt  and  its  companion,  GetDlgltemlnt,  are  most  often  used  with  edit 
controls,  they  can  also  be  used  to  set  the  text  field  of  other  controls,  such  as  static  text  con¬ 
trols.)  The  nCtrllD  variable  is  the  ID  number  of  the  scroll  bar;  adding  3  to  the  number  con¬ 
verts  it  to  the  ID  for  the  corresponding  numeric  label.  The  third  parameter  is  the  color 
value.  Normally,  the  fourth  parameter  would  be  set  to  TRUE  to  indicate  that  numbers 
greater  than  32,767  should  be  displayed  as  negatives.  For  this  program,  however,  the  values 
range  from  0  to  255,  so  the  fourth  parameter  has  no  effect. 

In  the  process  of  converting  COLORS1  to  COLORS2,  we  passed  more  and  more  of  the 
work  to  Windows.  The  earlier  version  called  CreateWindotu  10  times;  the  new  version  calls 
CreateWindow  once  and  CreateDialog  once.  But  if  you  think  that  we’ve  reduced  our 
CreateWindotu  calls  to  a  minimum,  get  a  load  of  this  next  program. 
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HEXCALC:  Window  or  Dialog  Box? 

Perhaps  the  epitome  of  lazy  programming  is  the  HEXCALC  program,  shown  in  Figure  10-9. 
This  program  doesn’t  call  CreateWindow  at  all,  never  processes  WM_PAINT  messages, 
never  obtains  a  device  context,  and  never  processes  mouse  messages.  Yet  it  manages  to  in¬ 
corporate  a  10-function  hexadecimal  calculator  with  a  full  keyboard  and  mouse  interface  in 
fewer  than  150  lines  of  source  code.  The  calculator  is  shown  in  Figure  10-10  on  page  459. 


HEXCALC.MAK 

// . - . 

//  HEXCALC.MAK  make  file 
// . - . 

hexcalc.exe:  hexcalc.obj  hexcalc.def  hexcalc.res 

$(WINLINK)  hexcalc,  hexcalc,  NUL,  $(WINLIB),  hexcalc 
rc  -t  hexcalc.res 

hexcalc.obj:  hexcalc. c 
$ ( W I NCC )  hexcalc. c 

hexcalc.res  :  hexcalc. rc  hexcalc. ico 
$ ( W I N RC )  hexcalc. rc 


HEXCALC.C 

/* . . . 

HEXCALC.C  --  Hexadecimal  Calculator 

(c)  Charles  Petzold,  1992 
. */ 


//include  <windows.h> 

//include  <1  i mi ts . h> 

//include  <stdlib.h> 

//include  <string.h> 

//include  <ctype.h> 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT.  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 


{ 


Figure  10-9.  The  HEXCALC  program. 


(continued) 
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static  char  szAppName  []  =  "HexCalc"  ; 
HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 


wndclass. style 

wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground  = 
wndclass.lpszMenuName 
wndcl ass. IpszCl ass  Name  = 

RegisterClass  (&wndclass) 

} 

hwnd  =  CreateDialog  (hlnstance, 
ShowWindow  (hwnd,  nCmdShow)  ; 


CS.HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

DLGWI NDOWEXTRA  ; 
hlnstance  ; 

Loadlcon  (hlnstance,  szAppName)  ; 
LoadCursor  (NULL,  IDC.ARROW)  ; 
COLOR_WI NDOW  +  1  ; 

NULL  ; 
szAppName  ; 


szAppName,  0,  NULL)  ; 


while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  ShowNumber  (HWND  hwnd,  DWORD  dwNumber) 


char  szBuffer  [20]  ; 

SetDlgltemText  (hwnd,  VK_ESCAPE,  strupr  (ltoa  (dwNumber,  szBuffer,  16)))  ; 
} 

DWORD  Cal  cl t  (DWORD  dwFirstNum,  short  nOperation,  DWORD  dwNum) 

{ 

switch  (nOperation) 

{ 


case 

return 

dwNum  ; 

case 

return 

dwFirstNum 

+ 

dwNum 

case 

•  _  i 

return 

dwFi rstNum 

- 

dwNum 

case 

1  *  1 

return 

dwFi rstNum 

* 

dwNum 

case 

return 

dwFirstNum 

& 

dwNum 

case 

•  i » 

• 

return 

dwFirstNum 

i 

i 

dwNum 

case 

•  *  i 

return 

dwFi rstNum 

* 

dwNum 

case 

return 

dwFi rstNum 

« 

dwNum 

(continued) 
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case  ’>'  :  return  dwFirstNum  >>  dwNum  ; 
case  '/’  :  return  dwNum  ?  dwFirstNum  /  dwNum  :  UL0NG_MAX  ; 
case  :  return  dwNum  ?  dwFirstNum  %  dwNum  :  UL0NG_MAX  ; 
default  :  return  0L  ; 

} 


long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  BOOL  bNewNumber  =  TRUE  ; 
static  DWORD  dwNumber,  dwFirstNum  ; 
static  short  nOperation  =  '  =  '  ; 

HWND  hButton  ; 

switch  (message) 

{ 

case  WM_KEYDOWN  :  //  left  arrow  -->  backspace 

if  (wParam  !=  VK_LEFT) 
break  ; 

wParam  =  VK_BACK  ; 

//  fall  through 

case  WM.CHAR  : 

if  ((wParam  =  toupper  (wParam))  ==  VK_RETURN) 
wParam  =  '  =  '  ; 


hButton  =  GetDlgltem  (hwnd,  wParam)  ; 


if  (hButton  !=  NULL) 

{ 

SendMessage  (hButton,  BM.SETSTATE,  1,  0L) 
SendMessage  (hButton,  BM_SETSTATE,  0,  0L) 
} 

else 


{ 

MessageBeep  (0)  ; 
break  ; 

} 

case  WM.COMMAND  : 

SetFocus  (hwnd)  ; 


//  fall  through 


if  (wParam  ==  VK_BACK)  //  backspace 

ShowNumber  (hwnd,  dwNumber  /=  16)  ; 

else  if  (wParam  ==  VICESCAPE)  //  escape 

ShowNumber  (hwnd,  dwNumber  =  0L)  ; 

else  if  (isxdigit  (wParam))  //  hex  digit 

{ 

if  (bNewNumber) 

{ 


(continued) 
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dwFirstNum  =  dwNumber  ; 
dwNumber  =  0L  ; 

} 

bNewNumber  =  FALSE  ; 

if  (dwNumber  <=  ULONG_MAX  »  4) 

ShowNumber  (hwnd,  dwNumber  =  16  *  dwNumber  +  wParam  - 
(isdigit  (wParam)  ?  '0'  :  'A'  -  10))  ; 

else 

MessageBeep  (0)  ; 

} 

else  //  operation 

{ 

if  ( IbNewNumber) 

ShowNumber  (hwnd,  dwNumber  = 

Cal  cl t  (dwFirstNum,  nOperation,  dwNumber))  ; 
bNewNumber  =  TRUE  ; 
nOperation  =  wParam  ; 

} 

return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


HEXCALC.RC 


/* . 

HEXCALC.RC  resource  script 

*/ 


//include  <windows.h> 

HexCalc  ICON  hexcalc.ico 

HexCalc  DIALOG  32768,  0,  102,  122 

STYLE  WS_OVERLAPPED  !  WS.CAPTION  !  WS.SYSMENU  !  WS_MI N IMI ZEBOX 


CLASS  "HexCalc” 

CAPTION  "Hex  Calculator" 
{ 


PUSHBUTTON 

"D", 

68, 

8, 

24, 

14, 

14 

PUSHBUTTON 

"A", 

65, 

8, 

40, 

14, 

14 

PUSHBUTTON 

ii  y  ii 

55, 

8, 

56, 

14, 

14 

PUSHBUTTON 

11411 

52, 

8, 

72, 

14, 

14 

PUSHBUTTON 

11  ^  ii 

49, 

8, 

88. 

14, 

14 

(continued) 


457 


SECTION  III:  USING  RESOURCES 


PUSHBUTTON  "0", 
PUSHBUTTON  "0", 
PUSHBUTTON  "E". 
PUSHBUTTON  "B", 
PUSHBUTTON  "8". 
PUSHBUTTON  "5", 
PUSHBUTTON  "2", 
PUSHBUTTON  "Back", 
PUSHBUTTON  "F". 
PUSHBUTTON  "C", 
PUSHBUTTON  T, 
PUSHBUTTON  "6", 
PUSHBUTTON  "3", 
PUSHBUTTON  "+", 
PUSHBUTTON 
PUSHBUTTON 
PUSHBUTTON  T, 
PUSHBUTTON  , 
PUSHBUTTON  "Equals 
PUSHBUTTON 
PUSHBUTTON 
PUSHBUTTON  "A", 
PUSHBUTTON  "<", 
PUSHBUTTON  ">", 

} 


48, 

8, 

104, 

14, 

14 

27, 

26, 

4, 

50, 

14 

69, 

26, 

24, 

14, 

14 

66, 

26, 

40, 

14, 

14 

56, 

26, 

56, 

14, 

14 

53. 

26, 

72. 

14, 

14 

50, 

26, 

88, 

14, 

14 

8. 

26, 

104, 

32, 

14 

70, 

44, 

24, 

14, 

14 

67, 

44, 

40, 

14, 

14 

57. 

44, 

56, 

14, 

14 

54, 

44, 

72, 

14, 

14 

51. 

44, 

88. 

14, 

14 

43. 

62, 

24, 

14, 

14 

45, 

62, 

40, 

14, 

14 

42. 

62, 

56, 

14, 

14 

47, 

62, 

72. 

14. 

14 

37, 

62, 

88, 

14, 

14 

61. 

62, 

104, 

32, 

14 

38, 

80, 

24, 

14, 

14 

124, 

80, 

40, 

14, 

14 

94, 

80. 

56, 

14. 

14 

60, 

80, 

72. 

14. 

14 

62, 

80, 

88, 

14, 

14 

H  EXCALC.  ICO 


HEXCALC.DEF 


HEXCALC.DEF  module  definition  file 


NAME  HEXCALC 

DESCRIPTION  'Hexadecimal  Calculator  (c)  Charles  Petzold,  1992' 


(continued) 
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EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


Hex  Calculator 


895B 


] 


HD11000 

00000 

00000 

00000 

00000 

|  0  |  |  Back  |  |  Equals  | 


Program  Fie  Manager 
Manager 


Figure  10-10.  The  HEXCALC  display. 

HEXCALC  is  a  normal  infix  notation  calculator  that  uses  C  notation  for  the  operations.  It 
works  with  unsigned  32-bit  integers  and  does  addition,  subtraction,  multiplication,  divi¬ 
sion,  and  remainders;  bitwise  AND,  OR,  and  exclusive  OR  operations;  and  left  and  right  bit 
shifts.  Division  by  0  causes  the  result  to  be  set  to  FFFFFFFF. 

You  can  use  either  the  mouse  or  keyboard  with  HEXCALC.  You  begin  by  “clicking  in”  or 
typing  the  first  number  (up  to  eight  hexadecimal  digits),  then  the  operation,  and  then  the  sec¬ 
ond  number.  You  can  then  show  the  result  by  clicking  the  Equals  button  or  by  pressing  either 
the  Equals  key  or  the  Enter  key.  To  correct  your  entries,  you  use  the  Back  button  or  the  Back¬ 
space  or  Left  Arrow  key.  Click  the  “display”  box  or  press  the  Esc  key  to  clear  the  current  entry. 

What’s  so  strange  about  HEXCALC  is  that  the  window  displayed  on  the  screen  seems 
to  be  a  hybrid  of  a  normal  overlapped  window  and  a  modeless  dialog  box.  On  the  one 
hand,  all  the  messages  to  HEXCALC  are  processed  in  a  function  called  WndProc  that 
appears  to  be  a  normal  window  procedure.  The  function  returns  a  long,  it  processes 
the  WM -DESTROY  message,  and  it  calls  DefWindowProc  just  like  a  normal  window 
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procedure.  On  the  other  hand,  the  window  is  created  in  WinMain  with  a  call  to 
CreateDialog  using  a  dialog  box  template  from  HEXCALC.RC.  So  is  HEXCALC  a  normal 
overlapped  window  or  a  modeless  dialog  box? 

The  simple  answer  is  that  a  dialog  box  is  a  window.  Normally,  Windows  uses  its  own 
internal  window  procedure  to  process  messages  to  a  dialog  box  popup  window.  Windows 
then  passes  these  messages  to  a  dialog  box  procedure  within  the  program  that  creates  the 
dialog  box.  In  HEXCALC  we  are  forcing  Windows  to  use  the  dialog  box  template  to  create  a 
popup  window,  but  we’re  processing  messages  to  that  window  ourselves. 

A  closer  look  at  HEXCALC.RC  will  reveal  how  this  is  done.  The  top  of  the  dialog  box 
template  looks  like  this: 

HexCalc  DIALOG  32768,  0.  102,  122 

STYLE  WS.OVERLAPPED  !  WS.CAPTION  !  WS.SYSMENU  !  WS_MI NIMI ZEBOX 
CLASS  "HexCalc" 

CAPTION  "Hex  Calculator" 

Notice  the  identifiers,  such  as  WS_OVERLAPPED  and  WS_MINIMIZEBOX,  which  we 
might  use  to  create  a  normal  window  using  a  CreateWindow  call.  The  CLASS  statement  is 
the  crucial  difference  between  this  dialog  box  and  the  others  we’ve  created  so  far.  When 
we  omitted  this  statement  in  previous  dialog  box  templates,  Windows  registered  a  window 
class  for  the  dialog  box  and  used  its  own  window  procedure  to  process  the  dialog  box  mes¬ 
sages.  The  inclusion  of  a  CLASS  statement  here  tells  Windows  to  send  the  messages  else¬ 
where — specifically,  to  the  window  procedure  specified  in  the  “HexCalc"  window  class. 

The  “HexCalc”  window  class  is  registered  in  the  WinMain  function  of  HEXCALC, 
just  like  a  window  class  for  a  normal  window.  However,  note  this  very  important  differ¬ 
ence:  The  cbWndExtra  field  of  the  WNDCLASS  structure  is  set  to  DLGWINDOWEXTRA. 
This  is  essential  for  dialog  procedures  that  you  register  yourself. 

After  registering  the  window  class,  WinMain  calls  CreateDialog : 

hwnd  =  CreateDialog  (hlnstance,  szAppName,  0,  NULL)  ; 

The  second  parameter  (the  string  “HexCalc")  is  the  name  of  the  dialog  box  template.  The 
third  parameter,  which  is  normally  the  window  handle  of  the  parent  window,  is  set  to  0  be¬ 
cause  the  window  has  no  parent.  The  last  parameter,  which  is  normally  the  address  of  the 
dialog  procedure,  isn’t  required  because  Windows  won’t  be  processing  the  messages  and 
hence  can’t  send  them  to  a  dialog  procedure. 

This  CreateDialog  call  in  conjunction  with  the  dialog  box  template  is  effectively 
translated  by  Windows  into  a  CreateWindow  call  that  does  the  equivalent  of  this: 

hwnd  =  CreateWindow  ("HexCalc",  "Hex  Calculator", 

WS.OVERLAPPED  !  WS.CAPTION  !  WS.SYSMENU  !  WS_M I N I M I Z EBOX 
CWJJSEDEFAULT,  CWJJSEDEFAULT, 

102  *  4  /  cxChar ,  122  *  8  /  cyChar, 

NULL,  NULL,  hlnstance,  NULL)  ; 

The  cxChar  and  cyChar  variables  are  the  width  and  height  of  a  system  font  character. 
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We  reap  an  enormous  benefit  from  letting  Windows  make  this  CreateWindow  call: 
Windows  will  not  stop  at  creating  the  1  popup  window  but  will  also  call  CreateWindow  for 
all  29  child  window  push-button  controls  defined  in  the  dialog  box  template.  All  these  con¬ 
trols  send  WM -COMMAND  messages  to  the  window  procedure  of  the  parent  window, 
which  is  none  other  than  WndProc.  This  is  an  excellent  technique  for  creating  a  window 
that  must  contain  a  collection  of  child  windows. 

Creatively  Using  Control  IDs 

HEXCALC  contains  no  header  file  with  identifiers  for  all  the  ID  numbers  of  the  child 
window  controls  in  the  dialog  box  template.  We  can  dispense  with  this  file  because  the 
ID  number  for  each  of  the  push-button  controls  is  set  to  the  ASCII  code  of  the  text  that 
appears  in  the  control.  This  means  that  WndProc  can  treat  WM -COMMAND  messages 
and  WM-CHAR  messages  in  much  the  same  way.  In  each  case,  wParam  is  the  ASCII  code 
of  the  button. 

Of  course,  a  little  massaging  of  the  keyboard  messages  is  necessary.  WndProc  traps 
WM-KEYDOWN  messages  to  translate  the  Left  Arrow  key  to  a  Backspace  key.  During  pro¬ 
cessing  of  WM-CHAR  messages,  WndProc  converts  the  character  code  to  uppercase  and 
the  Enter  key  to  the  ASCII  code  for  the  Equals  key. 

The  validity  of  a  WM_CHAR  message  is  checked  by  calling  GetDlgltem.  If  the 
GetDlgltem  function  returns  0,  then  the  keyboard  character  is  not  one  of  the  ID  numbers 
defined  in  the  dialog  box  template.  If  the  character  is  one  of  the  IDs,  however,  the  appro¬ 
priate  button  is  flashed  by  sending  it  a  couple  of  BM-SETSTATE  messages: 

if  (hButton  =  GetDlgltem  (hwnd,  wParam)) 

{ 

SendMessage  (hButton,  BM_SETSTATE,  1.  0L)  ; 

SendMessage  (hButton,  BM_SETSTATE,  0,  0L)  ; 

} 

This  adds  a  nice  touch  to  HEXCALC’s  keyboard  interface,  and  with  a  minimum  of  effort. 

When  WndProc  processes  WM-COMMAND  messages,  it  always  sets  the  input  focus 
to  the  parent  window: 

case  WM_COMMAND  : 

SetFocus  (hwnd)  ; 

Otherwise,  the  input  focus  would  be  shifted  to  one  of  the  buttons  whenever  it  was  clicked 
with  the  mouse. 


WORKING  WITH  FILES:  POPPAD  REVISITED 

When  we  added  a  menu  to  POPPAD  in  Chapter  9,  several  standard  menu  options  were  left 
unimplemented.  We  are  now  ready  to  add  logic  to  POPPAD  to  open  files,  read  them  in,  and 
save  the  edited  files  on  disk.  In  the  process,  well  also  add  search  and  replace  logic  to  POPPAD. 
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Working  with  files  under  Windows  has  gradually  improved  over  the  years.  Back  in 
the  days  of  Windows  1.0  and  2.0,  the  only  documented  file  I/O  function  was  OpenFile  (de¬ 
scribed  below),  and  the  officially  recommended  approach  to  reading  and  writing  files  was 
to  write  small  assembly  language  files  that  directly  accessed  MS-DOS  function  calls. 
Although  the  use  of  standard  C  run  time  library  functions  (such  as  read  and  fread)  was 
possible,  in  a  small  or  medium  model  program  these  functions  worked  only  with  near 
pointers.  This  was  a  nuisance  for  programs  that  maintained  file  data  in  global  memory  blocks. 

Fortunately,  many  programmers  soon  discovered  some  undocumented  functions  for 
working  with  files  using  far  pointers.  These  took  the  names  _ lopen ,  _ Iread ,  _ Iwrite ,  and  so 
forth,  and  they  hooked  almost  directly  into  MS-DOS  function  calls.  Beginning  with  Windows 
3.0,  these  functions  were  documented,  and  they’re  now  the  standard  file  I/O  functions  for 
Windows  programming. 

But  one  problem  still  remained:  Working  with  files  usually  requires  File  Open  and 
File  Save  dialog  boxes.  Dialog  procedures  for  these  dialog  boxes  can  be  very  complex  be¬ 
cause  of  the  interaction  between  list  boxes  and  edit  fields. 

With  Windows  3.1,  a  solution  to  this  problem  is  now  available.  Windows  3.1  includes 
an  enhancement  called  the  “common  dialog  box  library.”  This  library  consists  of  several 
functions  that  invoke  standard  dialog  boxes  for  opening  and  saving  files,  searching  and 
replacing,  choosing  colors,  choosing  fonts,  and  printing. 

To  use  these  functions,  you  basically  initialize  the  fields  of  a  structure  and  pass  a 
pointer  to  the  structure  to  a  function  in  the  common  dialog  box  library.  The  function 
creates  and  displays  the  dialog  box.  When  the  user  makes  the  dialog  box  go  away,  the  func¬ 
tion  you  called  returns  control  to  your  program,  and  you  obtain  information  from  the 
structure  you  passed  to  it. 

The  COMMDLG.H  header  file  defines  the  functions  and  structures  necessary  for 
using  these  dialog  boxes.  COMMDLG.LIB  is  the  common  dialog  box  import  library,  and 
COMMDLG.DLL  is  a  dynamic  link  library  containing  the  dialog  box  templates  and  pro¬ 
cedures.  Even  if  you  write  a  program  for  Windows  3.0,  you  can  include  COMMDLG.DLL 
with  your  distributed  code  to  use  these  dialog  boxes. 

The  Recommended  Methods 

With  Windows  3.1,  it  is  now  possible  to  unequivocally  recommend  the  best  and  easiest  way 
for  working  with  files  in  a  Windows  program: 

■  Use  the  File  Open  and  File  Close  dialog  boxes  included  in  the  common 
dialog  box  library.  Using  them  is  easier  than  writing  your  own  dialog  box 
procedures.  These  dialog  boxes  also  offer  the  user  a  high  level  of  consis¬ 
tency  among  Windows  applications.  All  the  programs  included  in  Windows 
3.1  that  use  file  I/O  take  advantage  of  the  common  dialog  box  library. 
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■  For  the  actual  file  I/O,  use  these  Windows  functions:  _ lereat ,  _ lopen , 

-Iclose,  _ head \  _ Iwrite ,  and  _ llseek  They  correspond  directly  to  the 
MS-DOS  Interrupt  0x21  function  calls  0x3C  through  0x40  and  0x42,  and 
they  use  MS-DOS  file  handles.  These  functions  have  the  advantage  of 
accepting  far  pointers,  so  you  can  use  them  with  global  memory  blocks  in 
small  or  medium  model  Windows  programs. 

■  Do  not  keep  files  open  for  long  periods  of  time.  More  specifically,  this 
means  you  should  not  keep  a  file  open  between  messages.  You  should 
open  or  create  a  file,  read  or  write  what  you  need  in  several  large  gulps, 
and  then  close  it — all  in  the  course  of  processing  a  single  message. 

The  old  FileOpen  function  is  not  used  much  any  more.  It  had  the  nice  feature  of 
being  able  to  create  and  save  a  fully  qualified  filename  based  on  the  current  directory,  but 
in  other  respects  FileOpen  was  clumsy  to  use.  Functions  in  the  common  dialog  box  library 
can  now  create  fully  qualified  filenames. 

You  can  use  the  standard  C  run  time  functions  fopen,  /read,  /write,  and  so  forth,  for 
buffered  file  I/O,  but  these  have  the  disadvantage  of  using  near  pointers  in  small  or 
medium  model  C  programs.  Also,  buffered  file  I/O  does  not  offer  any  speed  advantage  if 
you’re  reading  and  writing  files  in  large  chunks. 

You  can  also  use  the  standard  C  run  time  functions  open,  read,  write,  and  so  forth,  for 
low-level  file  I/O,  but  these  use  near  pointers.  If  you  use  these  functions,  do  not  assume 
that  the  file  handle  associated  with  these  functions  is  the  MS-DOS  file  handle.  Some  C  com¬ 
pilers  use  a  different  set  of  file  handles  for  these  functions.  Do  not  mix  these  functions  with 
the  Windows  file  I/O  functions  discussed  above. 

If  you  need  to  obtain  a  list  of  files  or  subdirectories  in  a  particular  directory,  you  don’t 
need  to  use  the  MS-DOS  “find  first  file”  and  “find  next  file”  functions.  You  can  create  a  hid¬ 
den  list  box  window  and  send  it  an  LB_DIR  message  (as  shown  in  the  HEAD  program  in 
Chapter  6).  You  can  then  simply  pull  all  the  filenames  and  directory  names  from  the  list 
box  using  the  LB-GETTEXT  message. 

If  you  need  to  execute  either  another  Windows  program  or  an  MS-DOS  program,  use 
the  Windows  function  WinExec.  For  other  file  and  disk  chores  that  do  not  deal  with  open 
files  (such  as  deleting  files  or  creating  directories),  you  can  use  functions  in  the  C  run  time 
library. 

Finally,  after  all  this,  if  you  really  need  to  make  an  MS-DOS  function  call  that  can’t  be 
duplicated  in  any  other  way,  use  the  Windows  function  DOS3Call  from  an  assembly  lan¬ 
guage  routine. 

The  Windows  File  I/O  Functions 

Windows  includes  six  functions  that  you  should  use  for  all  your  basic  file  I/O  chores.  These 
functions  are  equivalents  of  the  MS-DOS  handle -based  file  I/O  functions  first  introduced 
in  MS-DOS  2.0. 
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You’ll  first  want  to  define  a  variable  for  storing  a  file  handle: 

int  hFile  ; 

To  open  an  existing  file,  you  call  _ lopen : 

hFile  =  _lopen  (1 pszPathName,  i ReadWri te )  ; 

This  function  returns  an  MS-DOS  file  handle  or  -1  if  an  error  occurs.  Most  often  an  error 
indicates  that  the  file  could  not  be  found. 

The  first  parameter  is  a  filename.  It  can  be  fully  qualified,  but  if  it  isn’t,  MS-DOS  uses 
the  program’s  current  directory  to  locate  the  file.  Windows  maintains  a  separate  current 
directory  for  each  program.  The  second  parameter  is  a  combination  of  flags  that  are  de¬ 
fined  in  WINDOWS.H.  In  most  cases,  you’ll  use  two  flags. 

The  first  flag  tells  MS-DOS  whether  you  want  to  read  the  file,  write  to  the  file,  or  both: 
OF.READ,  OF_WRITE,  and  OF_READWRITE.  If  you  don’t  include  one  of  these  flags,  OF- 
_READ  is  the  default. 

The  second  flag  indicates  sharing  options.  These  flags  come  into  play  only  if  another 
program  has  a  file  open  that  your  program  wants  to  use  or  if  another  program  tries  to  open 
a  file  that  your  program  is  already  using.  The  OF_SHARE_EXCLUSIVE  flag  indicates  that 
you  want  exclusive  use  of  the  file.  If  another  program  has  the  file  open,  the  _ lopen  func¬ 
tion  will  fail.  During  the  time  the  file  is  open,  no  other  program  can  open  that  file.  This  is  a 
good  flag  to  use  if  you’re  writing  to  the  file. 

The  OF_SHARE_DENY_WRITE  flag  is  a  good  one  to  use  if  your  program  only  needs 
to  read  a  file.  This  flag  denies  access  to  any  other  program  trying  to  write  to  the  file,  which 
could  be  a  problem  if  you’re  trying  to  read  the  file!  The  OF_SHARE_DENY_READ  flag  is 
rarely  used;  it  prohibits  other  programs  from  reading  the  file  but  not  from  writing  to  it.  The 
OF_SHARE_DENY_NONE  flag  is  also  rarely  used  in  most  programs  because  it  allows  any 
other  program  to  open  the  same  file  for  reading  or  writing. 

The  OF_SHARE_COMPAT  flag  (which  is  equal  to  0)  is  provided  for  compatibility 
with  MS-DOS  programs  written  prior  to  MS-DOS  3.0.  It  allows  other  programs  that  open 
files  with  the  OF_SHARE_COMPAT  flag  (but  not  any  of  the  other  file-sharing  flags)  to  read 
from  and  write  to  the  file. 

In  conclusion,  you’ll  probably  use  one  of  these  three  forms  of  the  _ lopen  call: 

hFile  =  Jopen  OpszPathName.  OF.READ  !  OF_SHARE_DENY_WRITE)  ; 

hFile  =  Jopen  OpszPathName,  OF.WRITE  !  OF_SHARE_EXCLUSIVE)  ; 

hFile  =  Jopen  OpszPathName,  OF.READWRITE  !  OF_SHARE_EXC LUS I VE )  ; 

The  _ lopen  call  will  fail  if  the  file  does  not  exist,  if  the  path  could  not  be  found,  or  if 
the  sharing  options  are  not  compatible  with  another  program  that  has  the  file  open. 

To  create  and  open  a  new  file,  use  _ lereat : 

hFile  =  Jcreat  OpszPathName,  iAttribute)  ; 
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Again,  the  function  returns  an  MS-DOS  file  handle  or  -1  if  an  error  occurs.  The 
_ lereat  function  opens  the  file  in  the  compatibility  sharing  mode.  If  the  file  already  exists, 
_ lereat  truncates  it  to  a  0  byte  length.  The  second  parameter  is  a  file  attribute.  Use  0  for  a 
normal  file,  1  for  a  read-only  file,  2  for  a  hidden  file,  and  3  for  a  system  file. 

If  you  want  to  open  a  file  that  may  or  may  not  exist,  and  you  don’t  need  the  existing 
contents  of  the  file  if  the  file  already  exists,  you  can  simply  open  it  with  _ lereat .  However, 
if  you  want  to  preserve  the  existing  contents  of  the  file,  first  try  -lopen,  and  if  that  fails,  try 
_ lereat .  After  an  -lopen  or  -lereat  call,  the  file  pointer  is  set  initially  to  the  beginning  of 
the  file.  Normally,  all  reading  and  writing  is  sequential,  and  the  file  pointer  is  updated  after 
each  read  or  write.  However,  you  can  use  -llseek  (equivalent  to  the  MS-DOS  Interrupt  0x21 
function  call  0x42)  to  change  the  file  pointer: 

lPosition  =  _1 1  seek  (hFile,  1  Position,  i Method )  ; 

The  iMethod  parameter  should  be  set  to  one  of  the  following  values: 


Value  Purpose 

0  Move  the  file  pointer  lPosition  bytes  from  the  beginning  of  the  file. 

1  Move  the  file  pointer  lPosition  bytes  from  the  current  position  in  the  file. 

2  Move  the  file  pointer  lPosition  bytes  from  the  end  of  the  file. 

The  value  returned  from  -llseek  is  the  new  position  of  the  file  pointer  if  the  function  is 
successful  or  -1L  if  an  error  occurs. 

If  you  want  to  open  an  existing  file  and  add  data  to  the  end  of  it  without  destroying 
the  current  contents,  you  call: 

-  llseek  (hFile,  0L,  2)  ; 

This  moves  the  pointer  to  the  end  of  the  file.  You  can  also  use  _ llseek  to  determine  the  size 
of  an  open  file.  You  might  want  to  define  a  function  called  FileLength  to  do  this: 

long  FileLength  (int  hFile) 

{ 

long  leurrentpos  =  _11 seek  (hFile,  0L,  1)  ; 
long  1 Fi 1 eLength  =  _1 1  seek  (hFile,  0L,  2)  ; 

_1 1  seek  (hFile,  ICurrentPos,  0)  ; 
return  1 Fi 1 eLength  ; 

{ 

FileLength  saves  the  current  position  of  the  file  pointer  by  calling  -llseek  without  actually 
moving  the  pointer,  moves  the  file  pointer  to  the  end  of  the  file,  and  then  restores  the  file 
pointer  to  its  original  position. 

To  write  to  a  file,  use: 

wBytesWritten  =  _lwrite  (hFile,  IpBuffer,  wBytes)  ; 
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The  IpBuffer  is  a  pointer  to  the  data  that  you  want  to  write  to  the  file,  and  wBytes  is  the 
number  of  bytes  to  write.  The  file  buffer  cannot  extend  past  the  end  of  a  segment.  The 
wBytesWritten  value  returned  from  the  function  is  the  number  of  bytes  that  have  actually 
been  written  to  the  file.  Be  sure  to  check  this  value:  If  it’s  less  than  wBytes ,  you’ve  run  out  of 
disk  space.  Normally,  MS-DOS  allows  you  to  write  as  much  as  65,535  bytes  to  a  file  in  one 
call,  but  _ Iwrite  returns  -1  to  signal  an  error,  so  you’ll  want  to  restrict  yourself  to  65,534 
bytes  or  less.  If  wBytes  is  0,  MS-DOS  truncates  the  file  at  the  current  file  pointer. 

The  function  to  read  from  a  file  is  similar: 

wBytesRead  =_lread  (hFile,  IpBuffer,  wBytes)  ; 

The  IpBuffer  is  a  pointer  to  an  area  of  memory  that  receives  the  data  read  from  the  file,  and 
wBytes  is  the  number  of  bytes  to  read.  The  wBytesRead  value  returned  can  be  less  than 
wBytes  if  the  end  of  the  file  is  encountered  before  wBytes  is  read.  A  return  value  of  -1 
signals  an  error. 

Finally,  to  close  a  file,  use: 

_1  cl ose  (hFile)  ; 

When  working  with  files  and  global  memory  blocks,  you  may  also  need  to  use  string 
functions  that  work  with  far  pointers.  Windows  includes  functions  called  Istrlen,  Istrcpy, 
Istrcat,  and  Istrcmp  that  are  similar  to  the  normal  C  string  functions  strlen ,  strcpy ,  strcat , 
and  strcmp  except  that  they  use  far  pointers.  These  functions  are  useful  for  moving  0- 
terminated  data  between  two  global  memory  blocks  or  between  a  global  memory  block 
and  local  memory.  The  Istrcmp  function  is  case  sensitive  for  both  the  ASCII  and  ANSI  char¬ 
acter  sets,  and  it  can  accommodate  strings  with  multibyte  character  codes. 

For  more  extensive  string  and  memory  manipulation  in  global  memory  blocks,  both 
the  Microsoft  and  Borland  C  compilers  include  functions  beginning  with  the  prefix  _/ 
(such  as  _ fstrstr  and  _ fmemcpy )  that  work  with  far  pointers. 

Adding  File  Handling  to  POPPAD 

With  these  preliminaries  out  of  the  way,  we  are  now  ready  to  look  at  the  files  that  make  up 
POPPAD3.  These  are  shown  in  Figure  10-11. 

POPPAD3.MAK 

# 

#  P0PPAD3.MAK  make  file 

# 

poppad3.exe  :  poppad.obj  popfile.obj  popfind.obj  \ 

popfontB.obj  popprntO.obj  poppad.res  poppad.def 
KWINLINK)  poppad  popfile  popfind  popfontO  popprnt0,  poppad3,  \ 

Figure  10-11.  The  POPPAD3 program.  (continued) 
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NUL,  $( WINLIB) ,  poppad 
rc  -t  poppad. res  poppad3.exe 

poppad. obj  :  poppad. c  poppad. h 
$ ( WI NCC )  poppad. c 

popfile.obj  :  popfile.c 
$ ( WI NCC )  popfile.c 

popfind.obj  :  popfind.c 
$ ( WI NCC )  popfind.c 

popfontO.obj  :  popfont0.c 
HWINCC)  popfontO.c 

popprnt0.obj  :  popprnt0.c 
$ ( WI NCC )  popprnt0.c 

poppad. res  :  poppad. rc  poppad. h  poppad. ico 
$ ( WI NRC )  poppad. rc 


POPPAD.C 


/* . . . 

POPPAD.C  --  Popup  Editor 

(c)  Charles  Petzold,  1992 
.  . */ 

#include  <windows.h> 

#include  <commdlg.h> 
ifinclude  <stdlib.h> 

#include  "poppad. h" 

#define  EDITID  1 
#define  UNTITLED  "(untitled)" 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

BOOL  FAR  PASCAL  .export  AboutDlgProc  (HWND,  UINT,  UINT,  LONG)  ; 

//  Functions  in  POPFILE.C 


void  PopFilelnitialize  (HWND) 
BOOL  PopFileOpenDlg  (HWND, 
BOOL  PopFileSaveDlg  (HWND, 
BOOL  PopFileRead  (HWND, 
BOOL  PopFileWrite  (HWND, 


LPSTR, 

LPSTR, 

LPSTR) 

LPSTR) 


LPSTR)  ; 
LPSTR)  ; 


(continued) 
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//  Functions  in  POPFIND.C 

HWND  PopFindFindDlg  (HWND)  ; 

HWND  PopFi ndRepl aceDl g  (HWND)  ; 

BOOL  PopFindFindText  (HWND,  int  *,  LPFINDREPLACE)  ; 

BOOL  PopFi ndRepl aceText  (HWND,  int  *,  LPFINDREPLACE)  ; 

BOOL  PopFi ndNextText  (HWND,  int  *)  ; 

BOOL  PopFindValidFind  (void)  ; 

//  Functions  in  POPFONT.C 

void  PopFontlnitialize  (HWND)  ; 

BOOL  PopFontChooseFont  (HWND)  ; 

void  PopFontSetFont  (HWND)  ; 

void  PopFontDeinitialize  (void)  ; 

//  Functions  in  POPPRNT.C 

BOOL  PopPrntPrintFile  (HANDLE,  HWND,  HWND,  LPSTR)  ; 

//  Global  variables 

static  char  szAppName  []  =  "PopPad"  ; 
static  HWND  hDlgModeless  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

MSG  msg  ; 

HWND  hwnd  ; 

HANDLE  hAccel  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbrBackg round 
wndclass. IpszMenuName 
wndclass. lpszClassName 


CS_HREDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (hlnstance,  szAppName)  ; 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITE_BRUSH)  ; 
szAppName  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 

} 


hwnd  =  CreateWindow  (szAppName,  NULL, 

WS_OVERLAPP EDWIN DOW, 
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CWJJSEDEFAULT,  CWJJS ED E FAULT. 

CWJJSEDEFAULT.  CWJJSEDEFAULT. 

NULL,  NULL,  hlnstance,  1 pszCmdLine)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd); 

hAccel  =  LoadAccelerators  (hlnstance,  szAppName)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

if  (hDlgModeless  ==  NULL  !!  ! IsDialogMessage  (hDlgModeless,  &msg)) 
{ 

if  ( ITranslateAccelerator  (hwnd;  hAccel,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

} 

return  msg.wParam  ; 

} 

void  DoCaption  (HWND  hwnd,  char  *szTitleName) 
f 

char  szCaption  [64  +  _MAX_FNAME  +  _MAX_EXT]  ; 

wsprintf  (szCaption,  "%s  -  %s",  (LPSTR)  szAppName, 

(LPSTR)  (szTitleName  [0]  ?  szTitleName  :  UNTITLED))  ; 

SetWindowText  (hwnd,  szCaption)  ; 

} 

void  OkMessage  (HWND  hwnd,  char  *szMessage,  char  *szTitleName) 

{ 

char  szBuffer  [64  +  _MAX_FNAME  +  _MAX_EXT]  ; 

wsprintf  (szBuffer,  szMessage, 

(LPSTR)  (szTitleName  [0]  ?  szTitleName  :  UNTITLED))  ; 

MessageBox  (hwnd,  szBuffer,  szAppName,  MB_OK  !  MB_ICONEXCLAMATION)  ; 

} 

short  AskAboutSave  (HWND  hwnd,  char  *szTitleName) 

{ 

char  szBuffer  [64  +  _MAX_FNAME  +  _MAX_EXT]  ; 
short  nReturn  ; 

wsprintf  (szBuffer,  "Save  current  changes  in  %s?", 

(LPSTR)  (szTitleName  [0]  ?  szTitleName  ;  UNTITLED))  ; 


(continued) 
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nReturn  =  MessageBox  (hwnd,  szBuffer,  szAppName, 

MB_Y ESNOCANCEL  !  MB_I CONQU EST I ON )  ; 

if  (nReturn  ==  IDYES) 

if  USendMessage  (hwnd.  WM_COMMAND,  IDM_SAVE,  0L) ) 
nReturn  =  IDCANCEL  ; 


return  nReturn  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


{ 

static  BOOL 
static  char 
static  char 
static  FARPROC 
static  HANDLE 
static  HWND 
static  int 
static  UINT 
LONG 

LPFINDREPLACE 

WORD 


bNeedSave  =  FALSE  ; 

szFileName  [_MAX_PATH]  ; 

szTitleName  [_MAX_FNAME  +  _MAX_EXT]  ; 

lpfnAboutDlgProc  ; 

hlnst  ; 

hwndEdit  ; 

i Offset  ; 

messageFindReplace  ; 
lSelect  ; 

Ipfr  ; 
wEnable  ; 


switch  (message) 

{ 

case  WM_C REATE  : 

//  Get  About  dialog  box  instance  address 

hlnst  =  ( ( LPCREATESTRUCT)  1 Param) ->hlnstance  ; 
lpfnAboutDlgProc  =  MakeProcInstance  ((FARPROC)  AboutDl gProc, 

hlnst)  ; 

//  Create  the  edit  control  child  window 


hwndEdit  =  CreateWindow  ("edit",  NULL, 

WS.CHILD  !  WS.VISIBLE  !  WS.HSCROLL  !  WS.VSCROLL  ! 
WS.BORDER  !  ES.LEFT  !  ES_MULTI LINE  1 
ES.NOHIDESEL  !  ES.AUTOHSCROLL  !  ES.AUTOVSCROLL, 
0,  0,  0,  0, 

hwnd,  EDITID,  hlnst,  NULL)  ; 

SendMessage  (hwndEdit,  EM_L I M I TTEXT ,  32000,  0L)  ; 

//  Initialize  common  dialog  box  stuff 

PopFi lelnitial ize  (hwnd)  ; 

PopFontlnitial ize  (hwndEdit)  ; 
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messageFindReplace  =  RegisterWindowMessage  (FINDMSGSTRING)  ; 
//  Process  command  line 


lstrcpy  (szFileName,  (LPSTR) 

( ( ( LPCREATESTRUCT)  1 Param) ->1 pCreateParams ) )  ; 

if  (lstrlen  (szFileName)) 

{ 

GetFileTitle  (szFileName,  szTitleName, 
sizeof  (szTitleName))  ; 


if  ( ! PopFi 1 eRead  (hwndEdit,  szFileName)) 

OkMessage  (hwnd,  "File  %s  cannot  be  read!", 
szTitleName)  ; 


} 


DoCaption  (hwnd,  szTitleName)  ; 
return  0  ; 


case  WM_S ETFOCUS  : 

SetFocus  (hwndEdit)  ; 
return  0  ; 


case  WM_SIZE  : 

MoveWindow  (hwndEdit,  0,  0,  LOWORD  (IParam), 

H I WORD  (IParam),  TRUE)  ; 

return  0  ; 


case  WM_I NITMENUPOPUP  : 
switch  (IParam) 

{ 

case  1  :  //  Edit  menu 


//  Enable  Undo  if  edit  control  can  do  it 


Enabl eMenuItem  (wParam,  IDMJJNDO, 

SendMessage  (hwndEdit,  EM_CANUNDO,  0,  0L)  ? 
MF_ENAB LED  :  MF_GRAYED)  ; 

//  Enable  Paste  if  text  is  in  the  clipboard 

EnableMenuItem  (wParam,  IDM_PASTE, 

IsCl ipboardFormatAvai 1  able  (CF_TEXT)  ? 

MF.ENABLED  :  MF.GRAYED)  ; 

//  Enable  Cut,  Copy,  and  Del  if  text  is  selected 

lSelect  =  SendMessage  (hwndEdit,  EM_GETSEL,  0,  0L)  ; 
wEnable  =  HIWORD  (lSelect)  !=  LOWORD  (lSelect)  ? 

M F_ENAB LED  :  MF.GRAYED  ; 


(continued) 
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EnableMenuItem  (wParam,  IDM_CUT,  wEnable)  ; 
EnableMenuItem  (wParam,  IDM_C0PY,  wEnable)  ; 
EnableMenuItem  (wParam,  IDM_DEL,  wEnable)  ; 
break  ; 

case  2  :  //  Search  menu 

//  Enable  Find,  Next,  and  Replace  if  modeless 
//  dialogs  are  not  already  active 

wEnable  =  hDl gModel ess  ==  NULL  ? 

MF_ENAB LED  :  MF_GRAYED  ; 

EnableMenuItem  (wParam,  IDM_FIND,  wEnable)  ; 
EnableMenuItem  (wParam,  IDM_NEXT,  wEnable)  ; 
EnableMenuItem  (wParam,  IDM_REPLACE,  wEnable)  ; 
break  ; 

} 

return  0  ; 
case  WM_COMMAND  : 

//  Messages  from  edit  control 

if  ( LOWORD  (IParam)  &&  wParam  ==  EDITID) 

{ 

switch  (HI WORD  (IParam)) 

{ 

case  EN_UPDATE  : 

bNeedSave  =  TRUE  ; 
return  0  ; 

case  EN_ERRSPACE  : 
case  EN_MAXTEXT  : 

MessageBox  (hwnd,  "Edit  control  out  of  space.", 
szAppName,  MB_0K  !  MB.ICONSTOP)  ; 

return  0  ; 

} 

break  ; 

} 

switch  (wParam) 

{ 

//  Messages  from  File  menu 
case  IDM.NEW  : 

if  (bNeedSave  &&  IDCANCEL  == 

AskAboutSave  (hwnd,  szTitleName) ) 
return  0  ; 

SetWindowText  (hwndEdit,  ”\0”)  ; 
szFileName  [0]  =  '\0'  ; 
szTitleName  [0]  =  * \0 '  ; 
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DoCaption  (hwnd,  szTitleName)  ; 
bNeedSave  =  FALSE  ; 
return  0  ; 

case  I DM__OP EN  : 

if  (bNeedSave  &&  IDCANCEL  == 

AskAboutSave  (hwnd,  szTitleName)) 
return  0  ; 

if  ( PopFi 1 eOpenDl g  (hwnd,  szFileName,  szTitleName)) 

{ 

if  ( ! PopFi 1 eRead  (hwndEdit,  szFileName)) 

{ 

OkMessage  (hwnd.  "Could  not  read  file  %s!M. 

szTitleName)  ; 
szFileName  [0]  =  '\0'  ; 
szTitleName  [0]  =  '\0'  ; 

} 

} 

DoCaption  (hwnd,  szTitleName)  ; 
bNeedSave  =  FALSE  ; 
return  0  ; 

case  IDM_SAVE  : 

if  (szFileName  [0]) 

{ 

if  (PopFileWrite  (hwndEdit,  szFileName)) 

{ 

bNeedSave  =  FALSE  ; 
return  1  ; 

} 

else 

OkMessage  (hwnd,  "Could  not  write  file  %s", 
szTitleName)  ; 

return  0  ; 

} 

//  fall  through 

case  IDM.SAVEAS  : 

if  (PopFileSaveDlg  (hwnd,  szFileName,  szTitleName)) 

{ 

DoCaption  (hwnd,  szTitleName)  ; 

if  (PopFileWrite  (hwndEdit.  szFileName)) 

{ 

bNeedSave  =  FALSE  ; 
return  1  ; 

} 

else 
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OkMessage  (hwnd,  "Could  not  write  file  %s", 
szTitleName)  ; 


} 

return  0  ; 


case  I DM_PRI NT  : 

if  ( IPopPrntPrintFile  (hlnst,  hwnd,  hwndEdit, 
szTitleName)) 

OkMessage  (hwnd,  "Could  not  print  file  %s", 
szTitleName)  ; 

return  0  ; 


case  I DM_EX IT  : 

SendMessage  (hwnd,  WM_CL0SE,  0,  0L)  ; 
return  0  ; 


//  Messages  from  Edit  menu 


case  IDMJJNDO  : 

SendMessage  (hwndEdit,  WMJJNDO,  0,  0L)  ; 
return  0  ; 

case  IDM_CUT  : 

SendMessage  (hwndEdit,  WM.CUT,  0,  0L)  ; 
return  0  ; 

case  IDM_C0PY  : 

SendMessage  (hwndEdit,  WM.COPY,  0,  0L)  ; 
return  0  ; 

case  IDM_PASTE  : 

SendMessage  (hwndEdit,  WM_PASTE,  0,  0L)  ; 
return  0  ; 


case  IDM_DEL  : 

SendMessage  (hwndEdit,  WM_CLEAR,  0,  0L)  ; 
return  0  ; 


case  IDM.SELALL  : 

SendMessage  (hwndEdit,  EM_SETSEL,  0, 
MAKELONG  (0,  32767))  ; 

return  0  ; 


//  Messages  from  Search  menu 

case  IDM.FIND  : 

iOffset  =  H I WORD  ( 

SendMessage  (hwndEdit,  EM_GETSEL,  0,  0L))  ; 
hDl gModel ess  =  PopFindFindDlg  (hwnd)  ; 
return  0  ; 
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case  IDMJIEXT  : 

iOffset  =  H I WORD  ( 

SendMessage  (hwndEdit,  EM.GETSEL,  0,  0L))  ; 

if  (PopFindValidFind  0) 

PopFindNextText  (hwndEdit,  &iOffset)  ; 

else 

hDlgModeless  =  PopFindFindDlg  (hwnd)  ; 

return  0  ; 

case  I DM_REP LACE  : 

iOffset  =  H I WORD  ( 

SendMessage  (hwndEdit,  EM.GETSEL,  0,  0L))  ; 

hDlgModeless  =  PopFindReplaceDlg  (hwnd)  ; 
return  0  ; 

case  IDM_FONT  : 

if  (PopFontChooseFont  (hwnd)) 

PopFontSetFont  (hwndEdit)  ; 

return  0  ; 

//  Messages  from  Help  menu 
case  I DM_H E LP  : 

OkMessage  (hwnd,  "Help  not  yet  implemented!",  NULL)  ; 
return  0  ; 

case  IDM_ABOUT  : 

Dial ogBox  (hlnst,  "AboutBox",  hwnd,  1 pfnAboutDlgProc) ; 
return  0  ; 

} 

break  ; 

case  WM_CLOSE  : 

if  (IbNeedSave  !!  IDCANCEL  !=  AskAboutSave  (hwnd,  szTitleName))  . 
DestroyWi ndow  (hwnd)  ; 

return  0  ; 

case  WM_QUERYENDSESS I  ON  : 

if  (IbNeedSave  !!  IDCANCEL  !=  AskAboutSave  (hwnd,  szTitleName)) 
return  1L  ; 

return  0  ; 

case  WM_DESTROY  : 

PopFontDeiniti al ize  0  ; 
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PostQuitMessage  (0)  ; 
return  0  ; 

default  : 

//  Process  "Find-Replace"  messages 

if  (message  ==  messageFindReplace) 

{ 

lpfr  =  (LPFINDREPLACE)  IParam  ; 

if  (lpfr->Flags  &  FFLDIALOGTERM) 
hDl gModel ess  =  NULL  ; 

if  ( 1 pf r->Fl ags  &  FR_FI NDNEXT ) 

if  ( ! PopFi ndFi ndText  (hwndEdit,  &iOffset,  lpfr)) 
OkMessage  (hwnd,  "Text  not  found!",  NULL)  ; 

if  ( 1 pf r- > FI ags  &  FR_REPLACE  !! 

1 pf r- > Flags  &  FR_REPLACEALL) 

if  ( JPopFindReplaceText  (hwndEdit,  &iOffset,  lpfr)) 
OkMessage  (hwnd,  "Text  not  found!",  NULL)  ; 

if  ( 1 pf r -> FI ags  &  FR_REPLACEALL) 

while  (PopFindReplaceText  (hwndEdit,  &iOffset,  lpfr)) 

return  0  ; 

} 

break  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

BOOL  FAR  PASCAL  .export  AboutDlgProc  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM.INITDIALOG  : 
return  TRUE  ; 

case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  IDOK  : 

EndDialog  (hDlg,  0)  ; 
return  TRUE  ; 

} 

break  ; 

} 

return  FALSE  ; 

} 


476 


Chapter  10:  Dialog  Boxes 


POPFILE.C 


/* . 

POPFILE.C  --  Popup  Editor  File  Functions 

*/ 


//include  <windows.h> 
//include  <commdlg.h> 
//include  <stdlib.h> 


static  OPENFILENAME  ofn  ; 


void  PopFilelnitialize  (HWND  hwnd) 

{ 

static  char  *szFilter[]  =  {  "Text  Files  (*.TXT)'\  "*.txt", 

"ASCII  Files  (*.ASC)",  "*.asc", 

"All  Files  (*.*)", 

....  }  . 


ofn.lStructSize 
ofn.hwndOwner 
ofn.hlnstance 
ofn.lpstrFilter 
ofn.lpstrCustomFilter 
ofn.nMaxCustFil ter 
ofn.nFilterlndex 
ofn.lpstrFile 
ofn.nMaxFile 
ofn.lpstrFileTitle 
ofn.nMaxFileTitle 
ofn.lpstrlnitialDir 
ofn.lpstrTitle 
ofn. Flags 
ofn.nFileOffset 
ofn.nFileExtension 
ofn.lpstrDefExt 
ofn.lCustData 
ofn.lpfnHook 
ofn.lpTemplateName 
} 


sizeof  (OPENFILENAME)  ; 
hwnd  ; 

NULL  ; 

szFilter  [0]  ; 

NULL  ; 


NULL  ;  //  Set  in  Open  and  Close  functions 

_MAX_PATH  ; 

NULL  ;  //  Set  in  Open  and  Close  functions 

_MAX_FNAME  +  _MAX_EXT  ; 

NULL  ; 

NULL  ; 


//  Set  in  upen  and  uose  functions 


"txt"  ; 
0L  ; 
NULL  ; 
NULL  ; 


BOOL  PopFi 1 eOpenDl g  (HWND  hwnd.  LPSTR  IpstrFileName,  LPSTR  IpstrTitleName) 
{ 

ofn.hwndOwner  =  hwnd  ; 

ofn.lpstrFile  =  IpstrFileName  ; 

ofn.lpstrFileTitle  =  IpstrTitleName  ; 

ofn. Flags  =  OFN_CREATEPROMPT  ; 


return  GetOpenFileName  (&ofn)  ; 
} 
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BOOL  PopFileSaveDlg  (HWND 
{ 

ofn.hwndOwner 
ofn.lpstrFile 
ofn.lpstrFileTitle 
ofn. Flags 


hwnd,  LPSTR  1 pstrFileName,  LPSTR  1 pstrTitl eName) 
=  hwnd  ; 

=  1 pst r Fi 1 eName  ; 

=  1 pstrTitl eName  ; 

=  OFN.OVERWRITEPROMPT  ; 


return  GetSaveFi 1 eName  (&ofn)  ; 

} 

static  long  PopFi 1 eLength  (int  hFile) 

{ 

long  lCurrentPos  =  _1 1  seek  (hFile,  0L,  1)  ; 
long  1 Fi 1 eLength  =  _1 1  seek  (hFile,  0L,  2)  ; 

_1 1  seek  (hFile,  lCurrentPos,  0)  ; 


return  1 Fi 1 eLength  ; 
} 


BOOL  PopFileRead  (HWND  hwndEdit,  LPSTR  1 pstrFi 1 eName) 

{ 

long  1  Length  ; 

HANDLE  hBuffer  ; 
int  hFile  ; 

LPSTR  IpstrBuffer  ; 

if  (-1  ==  (hFile  =  Jopen  (IpstrFileName,  0F_READ  !  OF_SHARE_DENY_WRITE) ) ) 
return  FALSE  ; 

if  ( (1  Length  =  PopFi 1 eLength  (hFile))  >=  32000) 

{ 

_lclose  (hFile)  ; 
return  FALSE  ; 

} 

if  (NULL  ==  (hBuffer  =  GlobalAlloc  (GHND,  1  Length  +  1))) 

{ 

_lclose  (hFile)  ; 
return  FALSE  ; 

} 

IpstrBuffer  =  G1 obal Lock  (hBuffer)  ; 

_1 read  (hFile,  IpstrBuffer,  (WORD)  1  Length)  ; 

_1  cl ose  (hFile)  ; 

IpstrBuffer  [(WORD)  1  Length]  =  '\0'  ; 


SetWindowText  (hwndEdit,  IpstrBuffer)  ; 
G1 obal Unlock  (hBuffer)  ; 

Global  Free  (hBuffer)  ; 
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return  TRUE  ; 

} 

BOOL  PopFileWrite  ( HWND  hwndEdit,  LPSTR  1 pstrFi 1 eName) 

{ 

HANDLE  hBuffer  ; 
int  hFile  ; 

LPSTR  IpstrBuffer  ; 

WORD  wLength  ; 

if  (-1  ==  (hFile  =  Jopen  ( 1  pstrFi  1  eName ,  OF.WRITE  !  OF_SHARE_EXCLUSIVE) ) ) 
if  (-1  ==  (hFile  =  Jcreat  (1  pstrFi  1  eName,  0))) 
return  FALSE  ; 

wLength  =  GetWindowTextLength  (hwndEdit)  ; 

hBuffer  =  (HANDLE)  SendMessage  (hwndEdit,  EM_GETH ANDLE ,  0,  0L)  ; 
IpstrBuffer  =  (LPSTR)  Local  Lock  (hBuffer)  ; 

if  (wLength  !=  Jwrite  (hFile,  IpstrBuffer,  wLength)) 

{ 

_lclose  (hFile)  ; 
return  FALSE  ; 

} 

_lclose  (hFile)  ; 

LocalUnlock  (hBuffer)  ; 

return  TRUE  ; 

} 


POPFIND.C 

/* . 

POPFIND.C  --  Popup  Editor  Search  and  Replace  Functions 
.  . */ 


//include  <windows.h> 

//include  <commdlg.h> 

//include  <string.h> 

//define  MAX_STRING_LEN  256 

static  char  szFindText  [MAX_STRING_LEN]  ; 
static  char  szReplText  [MAX_STRING_LEN]  ; 

HWND  PopFindFindDlg  (HWND  hwnd) 

{ 

static  FINDREPLACE  fr  ;  //  must  be  static  for  modeless  dialog!!! 

fr.lStructSize  =  sizeof  (FINDREPLACE)  ; 

fr.hwndOwner  =  hwnd  ; 
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NULL  ; 

FR_H I DEUPDOWN  !  FR_H I DEMATCHCASE  !  FR_H I DEWHOLEWORD  ; 
szFindText  ; 

NULL  ; 

sizeof  (szFindText)  ; 

0  ; 

0  ; 

NULL  ; 

NULL  ; 

return  FindText  (&fr)  ; 

} 

HWND  PopFindReplaceDlg  (HWND  hwnd) 

{ 

static  FINDREPLACE  fr  ;  //  must  be  static  for  modeless  dialog!!! 

fr.lStructSize  =  sizeof  (FINDREPLACE)  ; 
fr.hwndOwner  =  hwnd  ; 

fr.hlnstance  =  NULL  ; 

fr. Flags  =  FR_H I DEUPDOWN  !  FR_H I DEMATCHCASE  I  FR_H I DEWHOLEWORD  ; 

fr.lpstrFindWhat  =  szFindText  ; 

fr.lpstrReplaceWith  =  szReplText  ; 

fr.wFindWhatLen  =  sizeof  (szFindText)  ; 

fr.wReplaceWithLen  =  sizeof  (szReplText)  ; 

fr.lCustData  =  0  ; 

fr.lpfnHook  =  NULL  ; 

fr.lpTemplateName  =  NULL  ; 

return  ReplaceText  (&fr)  ; 

} 

BOOL  PopFindFindText  (HWND  hwndEdit,  int  *piSearchOffset ,  LPFINDREPLACE  lpfr) 

{ 

int  iPos  ; 

LOCALHANDLE  hLocal  ; 

LPSTR  IpstrDoc,  IpstrPos  ; 

//  Get  a  pointer  to  the  edit  document 

hLocal  =  (HWND)  SendMessage  (hwndEdit,  EM_GETHANDLE,  0,  0L)  ; 

IpstrDoc  =  (LPSTR)  Local  Lock  (hLocal)  ; 

//  Search  the  document  for  the  find  string 

IpstrPos  =  _fstrstr  (IpstrDoc  +  *piSearchOffset,  lpfr->lpstrFindWhat)  ; 
LocalUnlock  (hLocal )  ; 

//  Return  an  error  code  if  the  string  cannot  be  found 

if  (IpstrPos  ==  NULL) 
return  FALSE  ; 
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//  Find  the  position  in  the  document  and  the  new  start  offset 
iPos  =  IpstrPos  -  IpstrDoc  ; 

♦piSearchOffset  =  iPos  +  _fstrlen  (lpfr->lpstrFindWhat)  ; 

//  Select  the  found  text 

SendMessage  (hwndEdit,  EM_SETSEL,  0, 

MAKELONG  (iPos,  *piSearchOffset) )  ; 

return  TRUE  ; 

} 

BOOL  PopFindNextText  (HWND  hwndEdit,  int  *piSearchOffset) 

{ 

FINDREPLACE  fr  ; 

fr.lpstrFi ndWhat  =  szFindText  ; 

return  PopFindFindText  (hwndEdit.  piSearchOffset,  &fr)  ; 

} 

BOOL  PopFindReplaceText  (HWND  hwndEdit.  int  *piSearchOffset,  LPFINDREPLACE  lpfr) 
{ 

//  Find  the  text 

if  ( ! PopFi ndFi ndText  (hwndEdit,  piSearchOffset,  lpfr)) 
return  FALSE  ; 

//  Replace  it 

SendMessage  (hwndEdit.  EM_REPLACESEL,  0,  (long)  1 pf r->l pstrRepl aceWi th )  ; 

return  TRUE  ; 

} 

BOOL  PopFi ndValidFind  (void) 

{ 

return  *szFindText  !=  ;'\0;'  ; 

} 


POPFONTO.C 


POPFONT0.C  --  Popup  Editor  Font  Functions  (dummy  version) 
. */ 

#include  <windows.h> 

BOOL  PopFontChooseFont  (HWND  hwnd) 

{ 
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return  FALSE  ; 

} 

void  PopFont I ni ti al ize  (HWND  hwndEdit) 
{ 

return  ; 

} 

void  PopFontSetFont  (HWND  hwndEdit) 

{ 

return  ; 

} 

void  PopFontDeinitial ize  (void) 

{ 

return  ; 

} 


POPPRNTO.C 


POPPRNT0.C  --  Popup  Editor  Printing  Functions  (dummy  version) 
. */ 

//include  <windows.h> 

BOOL  PopPrntPri ntFi 1 e  (HANDLE  hlnst,  HWND  hwnd,  HWND  hwndEdit, 

LPSTR  IpstrTitleName) 

{ 

return  FALSE  ; 

} 


POPPAD.RC 


POPPAD.RC  resource  script 

*/ 

//include  <windows.h> 

//include  "poppad.h" 

PopPad  ICON  "poppad.ico" 

PopPad  MENU 

{ 
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POPUP  "&File" 

{ 

MENUITEM  "&New",  IDM.NEW 

MENUITEM  "&Open. . IDM.OPEN 
MENUITEM  "&Save",  IDM_SAVE 

MENUITEM  "Save  &As...",  IDM.SAVEAS 

MENUITEM  SEPARATOR 

MENUITEM  "&Print . . I DM_PRI NT 
MENUITEM  SEPARATOR 

MENUITEM  "E&xit".  IDM.EXIT 

} 

POPUP  "&Edit" 

{ 

MENUITEM  "&Undo\tCtrl+Z",  IDM.UNDO 

MENUITEM  SEPARATOR 

MENUITEM  "Cu&t\tCtrl+X",  IDM.CUT 

MENUITEM  "&Copy\tCtrl+C",  IDM.COPY 

MENUITEM  "&Paste\tCtrl+V",  IDM_PASTE 

MENUITEM  "De&l eteUDel ",  IDM_DEL 

MENUITEM  SEPARATOR 

MENUITEM  "&Sel ect  All",  IDM.SELALL 

} 

POPUP  "&Search" 

{ 

MENUITEM  "&Find. . IDM_FIND 
MENUITEM  "Find  &Next\tF3",  I DM_N EXT 

MENUITEM  "&Repl ace. . I DM_REP LAC E 

} 

POPUP  "&Character" 

{ 

MENUITEM  "&Font . . ,  IDM_FONT 

} 

POPUP  "&Help" 

{ 

MENUITEM  "&Hel p",  I DM_H E LP 

MENUITEM  "&About  PopPad...,  IDM.ABOUT 

} 

} 

PopPad  ACCELERATORS 
{ 

"AZ",  IDMJJNDO 

VK.BACK,  IDM.UNDO,  VIRTKEY,  ALT 

"AX",  IDM.CUT 

VK_DELETE,  IDM.CUT,  VIRTKEY,  SHIFT 
"AC",  IDM_COPY 

VK_INSERT,  IDM.COPY,  VIRTKEY,  CONTROL 
"AV".  IDM_PASTE 
VK_I NSERT ,  IDM_PASTE,  VIRTKEY,  SHIFT 
VK_DELETE,  IDM.DEL,  VIRTKEY 
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VICF3,  IDM.NEXT,  VIRTKEY 

VK_F1,  IDM_HELP,  VIRTKEY 

} 

AboutBox  DIALOG  20,  20,  160,  80 
STYLE  WS.POPUP  !  WS.DLGFRAME 
{ 


CTEXT  "PopPad" 

-1, 

0, 

12. 

160, 

8 

ICON  "PopPad" 

-1, 

8. 

8. 

0. 

0 

CTEXT  "Popup  Editor 

for  Microsoft  Windows"  -1, 

0, 

36, 

160, 

8 

CTEXT  "Copyright  (c) 

Charles  Petzold,  1992"  -1, 

0, 

48, 

160, 

8 

DEFPUSHBUTTON  "OK" 

IDOK, 

64, 

60, 

32. 

14,  WS_GR0UP 

} 


PrintDlgBox  DIALOG  20,  20,  100,  76 

STYLE  WS_P0PUP  !  WS_CAPTION  !  WS_SYSMENU  I  WSJ/ISIBLE 
CAPTION  "PopPad" 

{ 


CTEXT  "Sending", 

CTEXT  "", 

CTEXT  "to  print  spooler.", 
DEFPUSHBUTTON  "Cancel", 

} 


-1,  0.  10,  100, 
IDD.FNAME,  0,  20,  100, 
-1,  0,  30,  100, 

IDCANCEL,  34.  50,  32, 


8 

8 

8 

14,  WS.GROUP 


POPPAD.H 


/* . 

POPPAD.H  header  file 

. */ 


//define  IDM.NEW  10 
//define  IDM_0PEN  11 
#def1ne  IDM_SAVE  12 
//def  i ne  IDM.SAVEAS  13 
//define  IDM_PRINT  14 
#def1ne  IDM_EXIT  15 

//define  IDMJJNDO  20 
//define  IDM_CUT  21 
#define  IDM.C0PY  22 
//define  IDM.PASTE  23 
//define  IDM.DEL  24 
//define  IDM_SELALL  25 

//define  IDM_FIND  30 
//define  IDM_NEXT  31 
//define  IDM.REPLACE  32 
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#define 

IDM_F0NT 

40 

#define 

IDM_HELP 

50 

^define 

IDM_AB0UT 

51 

#define 

IDD_FNAME 

10 

POPPAD.  ICO 

POPPAD.DEF 


;  POPPAD.DEF  module  definition 


file 


NAME 

DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Popup  Editor  (c)  Charles  Petzold,  1992' 

WINDOWS 

’WINSTUB.EXE’ 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


To  avoid  duplicating  source  code  in  chapters  to  come,  IVe  added  font  selection  and 
printing  to  the  menu  in  POPPAD.RC,  and  I’ve  added  WM_COMMAND  message  processing 
to  the  menu  in  POPPAD.C.  However,  the  implementation  of  these  features  is  not  shown 
here.  I’ll  upgrade  POPPAD  for  font  selection  in  Chapter  14  and  for  printing  in  Chapter  15. 

POPPAD.C  contains  all  the  basic  source  code  for  the  program.  POPFILE.C  has  the 
code  to  invoke  the  File  Open  and  File  Save  dialog  boxes,  and  it  also  contains  the  file  I/O 
routines.  POPFIND.C  contains  the  search  and  replace  logic.  POPFONTO.C  and  POP- 
PRNTO.C  don’t  do  very  much:  POPFONTO.C  will  be  replaced  with  POPFONT.C  in  Chapter 
14  to  create  POPPAD4,  and  POPPRNTO.C  will  be  replaced  with  POPPRNT.C  in  Chapter  15  to 
create  the  final  POPPAD  program. 
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Let’s  look  at  POPPAD.C  first.  You’ll  notice  in  WinMain  that  the  IpszCmclLine  parame¬ 
ter  is  used  as  the  last  field  of  the  CreateWindow  call.  This  string  might  contain  a  filename 
that  was  entered  as  a  command-line  parameter  to  POPPAD3  when  the  program  was  exe¬ 
cuted.  During  processing  of  the  WM -CREATE  message  in  WndProc,  this  filename  is 
passed  the  PopFileRead  function  located  in  POPFILE.C. 

POPPAD.C  maintains  two  filename  strings:  The  first  (stored  in  WndProc  using  the 
name  szFileName )  is  the  fully  qualified  drive,  path,  and  filename.  The  second  (stored  as 
szTitleName )  is  the  filename  by  itself.  This  is  used  in  the  DoCaption  function  in  POPPAD3 
to  display  the  filename  in  the  title  bar  of  the  window  and  is  used  in  the  OKMessage  and 
AskAboutSave  functions  to  display  message  boxes  to  the  user. 

POPFILE.C  contains  several  functions  to  display  the  File  Open  and  File  Save  dialog 
boxes  and  to  perform  the  actual  file  I/O.  The  dialog  boxes  are  displayed  using  the  func¬ 
tions  GetOpenFileName  and  GetSaveFileName ,  located  in  the  common  dialog  box  dynamic 
link  library  (COMMDLG.DLL).  Both  of  these  functions  use  a  structure  of  type  OPEN- 
FILENAME,  defined  in  COMMDLG.H.  In  POPFILE.C,  a  global  variable  named  ofn  is  used 
for  this  structure.  Most  of  the  fields  of  ofn  are  initialized  in  the  PopFilelnitialize  function, 
which  POPPAD.C  calls  when  processing  the  WM-CREATE  message  in  WndProc. 

It’s  convenient  to  make  ofn  a  static  global  structure  because  GetOpenFileName  and 
GetSaveFileName  return  some  information  to  the  structure  that  should  be  used  in  subse¬ 
quent  calls  to  these  functions. 

Although  common  dialog  boxes  have  a  lot  of  options — including  setting  your  own 
dialog  box  template  and  hooking  into  the  dialog  box  procedure — my  use  of  the  File  Open 
and  File  Save  dialog  boxes  in  POPFILE.C  is  quite  basic.  The  only  fields  of  the  OPEN- 
FILENAME  structure  that  are  set  are  iStructSize  (the  size  of  the  structure),  hwndOwner 
(the  dialog  box’s  owner),  IpstrFilter  (which  I’ll  discuss  shortly),  IpstrFile  and  nMaxFile  (a 
pointer  to  a  buffer  to  receive  the  fully  qualified  filename  and  the  size  of  that  buffer), 
IpstrFileTitle  and  nMaxFileTitle  (a  buffer  and  its  size  for  the  filename  by  itself),  Flags 
(which  sets  options  for  the  dialog  box),  and  IpstrDefExt  (which  is  set  to  a  text  string  con¬ 
taining  the  default  filename  extension  if  the  user  does  not  specify  one  when  typing  a  file¬ 
name  in  the  dialog  box). 

When  the  user  selects  Open  from  the  File  menu,  POPPAD3  calls  POPFILE’s  Pop- 
FileOpenDlg  function,  passing  to  it  the  window  handle,  a  pointer  to  the  filename  buffer, 
and  a  pointer  to  the  file  title  buffer.  PopFileOpenDlg  sets  the  hwndOwner ;  IpstrFile , 
and  IpstrFileTitle  fields  of  the  OPENFILENAME  structure  appropriately,  sets  Flags  to 
OFN-CREATEPROMPT,  and  then  calls  GetOpenFileName ,  which  displays  the  familiar 
dialog  box  shown  in  Figure  10-12. 

When  the  user  ends  this  dialog  box,  the  GetOpenFileName  function  returns.  The 
OFN_CREATEPROMPT  flag  instructs  GetOpenFileName  to  display  a  message  box  asking 
the  user  whether  the  file  should  be  created  if  the  selected  file  does  not  exist. 

The  combo  box  in  the  lower  left  corner  lists  the  types  of  files  that  will  be  displayed  in 
the  file  list.  This  is  known  as  a  “filter.”  The  user  can  change  the  filter  by  selecting  another 
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PopPad  -  (untitled) 


File  Edit  Search  Character  Help 


Program 

Manager 


Re  Manager 


Figure  10-12.  The  File  Open  dialog  box. 

file  type  from  the  combo  box  list.  In  the  PopFilelnitialize  function  in  POPFILE.C,  I  define  a 
filter  in  the  variable  szFilter  (an  array  of  character  strings)  for  three  types  of  files:  text  files 
with  the  extension  .TXT,  ASCII  files  with  the  extension  .ASC,  and  all  files.  A  pointer  to  the 
first  string  in  this  array  is  set  to  the  IpstrFilter  field  of  the  OPENFILENAME  structure. 

If  the  user  changes  the  filter  when  the  dialog  box  is  active,  the  nFilterlndex  field  of 
OPENFILENAME  reflects  the  user’s  choice.  Because  the  structure  is  stored  as  a  static 
variable,  the  next  time  the  dialog  box  is  invoked,  the  filter  will  be  set  to  the  selected  file  type. 

The  PopFileSaveDlg  function  in  POPFILE.C  is  similar.  It  sets  the  Flags  parameter  to 
OFN-OVERWRITEPROMPT  and  calls  GetSaveFileName  to  invoke  the  File  Save  dialog 
box.  The  OFN-OVERWRITEPROMPT  flag  causes  a  message  box  to  be  displayed  asking 
the  user  whether  a  file  should  be  overwritten  if  the  selected  file  already  exists.  The  other 
functions  in  POPFILE.C  perform  file  I/O  using  the  Windows  functions  I  discussed  earlier. 

Search  and  Replace 

The  common  dialog  box  library  also  includes  two  dialog  boxes  for  the  text  search  and 
replace  functions.  These  two  functions  ( FindText  and  ReplaceText )  use  a  structure  of  type 
FINDREPLACE.  The  POPFIND.C  file  shown  in  Figure  10-11  has  two  routines  ( PopFind - 
FindDlg  and  PopFind ReplaceDlg)  to  call  these  functions,  and  it  also  has  a  couple  of  func¬ 
tions  to  search  through  the  text  in  the  edit  control  and  to  replace  text. 

There  are  a  few  considerations  with  using  the  search  and  replace  functions.  First,  the 
dialog  boxes  they  invoke  are  modeless  dialog  boxes,  which  means  you  should  alter  your 
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message  loop  to  call  IsDialogMessage  when  the  dialog  boxes  are  active.  Second,  the 
FINDREPLACE  structure  you  pass  to  FindText  and  ReplaceText  must  be  a  static  variable; 
because  the  dialog  box  is  modal,  the  functions  return  after  the  dialog  box  is  displayed 
rather  than  after  it’s  destroyed.  Nevertheless,  the  dialog  box  procedure  must  be  able  to  con¬ 
tinue  to  access  the  structure. 

Third,  while  the  FindText  and  ReplaceText  functions  are  displayed,  they  communi¬ 
cate  with  the  owner  window  through  a  special  message.  The  message  number  can  be 
obtained  by  calling  the  RegisterWindowMessage  function  with  the  FINDMSGSTRING  pa¬ 
rameter.  This  is  done  while  processing  the  WM -CREATE  message  in  WndProc,  and  the 
message  number  is  stored  in  a  static  variable. 

While  processing  the  default  message  case,  WndProc  compares  the  message  variable 
with  the  value  returned  from  RegisterWindowMessage .  The  iParam  message  parameter  is  a 
far  pointer  to  the  FINDREPLACE  structure,  and  the  Flags  field  indicates  whether  the  user 
has  used  the  dialog  box  to  find  text  or  replace  text  or  whether  the  dialog  box  is  terminating. 
POPPAD3  calls  the  PopFindFindText  and  PopFindReplaceText  functions  in  POPFIND.C  to 
perform  the  search  and  replace  functions. 


THE  ONE  FUNCTION  CALL  WINDOWS  PROGRAM 

So  far  I’ve  shown  two  programs  that  let  you  view  selected  colors:  COLORS1  in  Chapter  6 
and  COLORS2  in  Chapter  10.  Now  it’s  time  for  COLORS3,  a  program  that  makes  only  one 
Windows  function  call.  The  COLORS3  source  code  is  shown  in  Figure  10-13. 

The  one  Windows  function  that  COLORS3  calls  is  ChooseColor ;  another  function  in 
the  common  dialog  box  library.  It  displays  the  dialog  box  shown  in  Figure  10-14  on  page 
490.  Color  selection  is  similar  to  that  in  COLORS1  and  COLORS2,  but  it’s  somewhat  more 
interactive. 

COLORS3.MAK 

# 

#  C0L0RS3.MAK  make  file 

# 

colors3.exe  :  colors3.obj  colors3.def 

$(WINLINK)  colors3,  colors3,  NUL,  $( WINLIB) ,  colors3 
rc  -t  colors3.exe 

colors3.obj  :  colors3.c 
$ ( WI NCC )  colors3.c 

Figure  10-13.  The  COLORS^ program. 
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COLORS3.C 

/* . . 

C0L0RS3.C  --  Version  using  Common  Dialog  Box 
(c)  Charles  Petzold,  1992 
. . . */ 

#include  <windows.h> 

#include  <commdlg.h> 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  CHOOSECOLOR  cc  ; 

static  DWORD  dwCustColors  [16]  ; 

cc.lStructSize  =  sizeof  (CHOOSECOLOR)  ; 

cc.hwndOwner  =  NULL  ; 

cc. hlnstance  =  NULL  ; 

cc.rgbResult  =  RGB  (0x80,  0x80,  0x80)  ; 

cc.lpCustColors  =  dwCustColors  ; 

cc. Flags  =  CC_RGBINIT  !  CC_FULLOPEN  ; 

cc.lCustData  =  0L  ; 

cc.l pfnHook  =  NULL  ; 

cc.lpTemplateName  =  NULL  ; 

return  ChooseColor  (&cc)  ; 

} 


COLORS3.DEF 


C0L0RS3. DEF  module  definition  file 


NAME  C0L0RS3 

DESCRIPTION  ’Color  Common  Dialog  Box  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  ’WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 
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Figure  10-14.  The  COLORS3  display. 

The  CbooseColor  function  uses  a  structure  of  type  CHOOSECOLOR  and  an  array  of 
16  DWORDs  to  store  custom  colors  that  the  user  selects  from  the  dialog  box.  The  rghResult 
field  can  be  initialized  to  a  color  value  that  will  be  displayed  if  the  CC-RGBINIT  flag  is  set 
in  the  Flags  field.  When  using  the  function  normally,  the  rgbResult  field  will  be  set  to  the 
color  that  the  user  selects. 

Notice  that  the  hwndOwner  field  of  the  Color  dialog  box  is  set  to  NULL.  When  the 
CbooseColor  function  calls  DialogBox  to  display  the  dialog  box,  the  third  parameter  to 
DialogBox  is  also  set  to  NULL.  This  is  perfectly  legitimate.  It  means  that  the  dialog  box  is 
not  owned  by  another  window.  The  caption  in  the  dialog  box  will  appear  in  the  Task  List, 
and  the  dialog  box  will  seem  to  function  much  like  a  normal  window. 

You  can  also  use  this  technique  with  your  own  dialog  boxes  in  your  own  programs. 
It's  possible  to  make  a  Windows  program  that  only  creates  a  dialog  box  and  does  all  pro¬ 
cessing  within  the  dialog  box  procedure. 
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CHAPTER  11 


An 

Introduction 
to  GDI 


We  have  been  using  Graphics  Device  Interface  (GDI)  functions  since  Chapter  1,  when  we 
first  started  writing  to  the  client  area  of  our  windows.  Now  it’s  time  for  a  more  formal 
coverage  of  the  subject.  This  chapter  discusses  the  preliminaries  of  GDI  but  stops  short  of 
drawing  graphics,  which  is  the  subject  of  Chapter  12.  Chapter  13  covers  bitmaps  and 
metafiles,  which  are  means  of  storing  graphical  information;  Chapter  14  discusses  text  and 
fonts;  and  Chapter  15  deals  with  printing. 

THE  GDI  PHILOSOPHY 

Graphics  in  Windows  are  handled  primarily  by  functions  exported  from  the  GDI. EXE 
module  (although  some  drawing  functions  actually  have  entry  points  in  the  USER.EXE 
file).  The  GDI.EXE  module  calls  routines  in  the  various  driver  files — a  .DRV  for  the  video 
display  screen  and  possibly  one  or  more  other  .DRV  driver  files  that  control  printers  or  plot¬ 
ters.  The  video  driver  accesses  the  hardware  of  the  video  display.  Different  video  display 
adapters  and  printers  require  different  driver  files. 
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The  GDI  system  is  constructed  so  that  Windows  can  determine  from  the  driver  what 
the  driver  itself  can  and  cannot  handle.  For  instance,  if  the  video  hardware  includes  a 
graphics  coprocessor  that  can  draw  ellipses,  then  GDI  can  take  advantage  of  that;  other¬ 
wise,  the  GDI  module  itself  must  calculate  the  points  of  the  ellipse  and  pass  the  points  to 
the  driver. 

Because  a  large  number  of  different  display  devices  can  be  attached  to  PC  com¬ 
patibles,  one  of  the  primary  goals  of  GDI  is  to  support  device-independent  graphics  on 
output  devices  such  as  video  displays,  printers,  and  plotters.  Windows  programs  should  be 
able  to  run  without  problems  on  any  graphics  output  device  that  Windows  supports.  GDI 
accomplishes  this  goal  by  providing  facilities  to  insulate  your  programs  from  the  particular 
characteristics  of  different  output  devices.  In  this  way  it  is  like  other  device-independent 
graphics  programming  languages.  But  Windows  GDI  is  different  in  its  strong  support  of 
pixel-level  manipulation. 

The  world  of  graphics  output  devices  is  divided  into  two  broad  groups:  raster  devices 
and  vector  devices.  Most  PC  output  devices  are  raster  devices,  which  means  that  they 
represent  images  as  a  pattern  of  dots.  This  category  includes  video  display  adapters,  dot¬ 
matrix  printers,  and  laser  printers.  Vector  devices,  which  draw  images  using  lines,  are 
generally  limited  to  plotters. 

Although  most  video  display  adapters  and  printers  are  raster  devices,  most  graphics 
interface  languages  are  based  solely  on  vectors.  This  means  that  a  program  using  one  of 
these  graphics  languages  is  a  level  of  abstraction  away  from  the  hardware.  The  output  de¬ 
vice  is  using  pixels  for  a  graphics  representation,  but  the  program  is  not  talking  to  the  inter¬ 
face  in  terms  of  pixels.  While  you  can  certainly  use  Windows  GDI  as  a  high-level  vector 
drawing  system,  you  can  also  use  it  for  relatively  low-level  pixel  manipulation. 

In  this  respect,  Windows  GDI  is  to  other  graphics  interface  languages  what  C  is  to 
other  programming  languages.  C  is  well  known  for  its  high  degree  of  portability  among 
different  operating  systems  and  environments.  Yet  C  is  also  well  known  for  allowing  a  pro¬ 
grammer  to  perform  low-level  system  functions  that  are  often  impossible  in  other  high- 
level  languages.  Just  as  C  is  sometimes  thought  of  as  a  “high-level  assembly  language,”  you 
can  think  of  GDI  as  a  high-level  interface  to  the  hardware  of  the  graphics  device. 

As  you’ve  seen,  by  default  Windows  uses  a  coordinate  system  based  on  pixels.  Most 
other  graphics  languages  use  a  “virtual”  coordinate  system  with  horizontal  and  vertical 
axes  that  range  (for  instance)  from  0  to  32,767.  Although  some  graphics  languages  don’t  let 
you  use  pixel  coordinates,  Windows  GDI  lets  you  use  either  system  (as  well  as  additional 
coordinate  systems  based  on  physical  measurements).  You  can  use  a  virtual  coordinate 
system  and  keep  your  program  distanced  from  the  hardware,  or  you  can  use  the  device 
coordinate  system  and  snuggle  right  up  to  the  hardware. 

Some  programmers  think  that  after  you  start  working  in  terms  of  pixels,  you’ve  aban¬ 
doned  device  independence.  We’ve  already  seen  that  this  is  not  necessarily  true.  The  trick 
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is  to  use  the  pixels  in  a  device-independent  fashion.  This  requires  that  the  graphics  inter¬ 
face  language  provide  facilities  for  a  program  to  determine  the  hardware  characteristics  of 
the  device  and  make  appropriate  adjustments.  For  instance,  we’ve  frequently  used  the 
pixel  size  of  a  standard  system  font  character  to  space  text  on  the  screen.  This  approach 
allows  our  programs  to  adjust  to  different  display  adapters  with  different  resolutions, 
text  sizes,  and  aspect  ratios.  You’ll  see  other  methods  in  this  chapter  for  determining 
display  sizes. 

Windows  can  run  on  either  a  monochrome  display  or  a  color  display.  If  you  choose, 
you  can  write  a  program  without  worrying  very  much  about  color.  If  you  use  color  in  your 
program  and  the  program  later  runs  on  a  monochrome  display  adapter,  Windows  will  use 
a  shade  of  gray  to  represent  each  color.  However,  you  can  also  determine  from  your  pro¬ 
gram  how  many  colors  are  available  on  the  particular  display  device  and  take  best  advan¬ 
tage  of  the  hardware. 

Of  course,  just  as  you  can  write  C  programs  that  have  subtle  portability  problems 
when  they  run  on  other  computers,  you  can  also  inadvertently  let  device  dependencies 
creep  into  your  Windows  programs.  That’s  part  of  the  price  of  not  being  fully  insulated 
from  the  hardware.  We’ll  examine  many  of  the  device-dependent  traps  in  the  next  few 
chapters. 

You  should  also  be  aware  of  the  limitations  of  Windows  GDI.  GDI  is  not  (at  this  time) 
capable  of  doing  everything  you  may  want  a  graphics  interface  to  do.  Although  you  can 
move  graphics  objects  around  the  display,  GDI  is  generally  a  static  display  system  with  no 
real  animation  support.  GDI  provides  no  direct  support  for  three-dimensional  representa¬ 
tions  or  for  rotations  of  objects.  For  instance,  when  you  draw  an  ellipse,  the  ellipse  axes 
must  be  parallel  to  the  horizontal  and  vertical  coordinates.  Although  some  graphics  lan¬ 
guages  use  floating-point  numbers  for  virtual  coordinates,  Windows — for  performance 
reasons — always  uses  16-bit  signed  integers. 

THE  DEVICE  CONTEXT 

When  you  want  to  draw  on  a  graphics  output  device  (such  as  the  screen  or  a  printer),  you 
must  first  obtain  a  handle  to  a  device  context  (or  DC).  In  giving  your  program  this  handle, 
Windows  is  giving  you  permission  to  use  the  device.  You  then  include  the  handle  as  a 
parameter  in  the  GDI  functions  to  identify  to  Windows  the  device  you  want  to  draw  on. 

The  device  context  contains  many  current  “attributes”  that  determine  how  the  GDI 
functions  work  on  the  device.  These  attributes  allow  the  parameters  to  the  GDI  functions 
to  include  only  starting  coordinates  or  sizes  and  not  everything  else  that  Windows  needs  to 
display  the  object  on  the  device.  For  example,  when  you  call  TextOut ,  you  need  specify  in 
the  function  only  the  device  context  handle,  the  starting  coordinates,  the  text,  and  the 
length  of  the  text.  You  don’t  need  to  specify  the  font,  the  color  of  the  text,  the  color  of  the 
background  behind  the  text,  and  the  intercharacter  spacing,  because  these  attributes  are 
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part  of  the  device  context.  When  you  want  to  change  one  of  these  attributes,  you  call  a 
function  that  changes  the  attribute  in  the  device  context.  Subsequent  TextOut  calls  use  the 
changed  attribute. 

Getting  the  Handle  to  the  Device  Context 

Windows  provides  several  methods  for  obtaining  a  device  context  handle.  If  you  obtain  a 
device  context  handle  while  processing  a  message,  you  should  release  it  (or  delete  it) 
before  exiting  the  window  function.  After  you  release  the  handle,  it  is  no  longer  valid. 

The  most  common  method  for  obtaining  a  device  context  handle  and  then  releasing 
it  involves  using  the  BeginPaint  and  EndPaint  calls  when  processing  the  WM_PAINT 
message: 

hdc  =  BeginPaint  (hwnd,  Xps)  ; 

[other program  lines] 

EndPaint  (hwnd,  &ps)  ; 

The  variable  ps  is  a  structure  of  type  PAINTSTRUCT.  The  hdc  field  of  this  structure  is  the 
handle  to  the  device  context  that  BeginPaint  returns.  The  PAINTSTRUCT  structure  also 
contains  a  RECT  (rectangle)  structure  named  rcPaint  that  defines  a  rectangle  encompass¬ 
ing  the  invalid  region  of  the  window’s  client  area.  With  the  device  context  handle  obtained 
from  BeginPaint ,  you  can  draw  only  within  this  region.  The  BeginPaint  call  validates  this 
region. 

Windows  programs  can  also  obtain  a  handle  to  a  device  context  during  processing  of 
messages  other  than  WM_PAINT: 

hdc  =  GetDC  (hwnd)  ; 

[other program  lines] 

ReleaseDC  (hwnd,  hdc)  ; 

This  device  context  applies  to  the  client  area  of  the  window  whose  handle  is  hwnd.  The 
primary  difference  between  the  use  of  these  calls  and  the  use  of  the  BeginPaint  and  End¬ 
Paint  combination  is  that  you  can  draw  on  your  entire  client  area  with  the  handle  returned 
from  GetDC.  However,  GetDC  and  ReleaseDC  don’t  validate  any  possibly  invalid  regions  of 
the  client  area. 

A  Windows  program  can  also  obtain  a  handle  to  a  device  context  that  applies  to  the 
entire  window  and  not  only  to  the  window’s  client  area: 

hdc  =  GetWindowDC  (hwnd)  ; 

[other program  lines] 

ReleaseDC  (hwnd,  hdc)  ; 

This  device  context  includes  the  window  caption  bar,  menu,  scroll  bars,  and  frame 
in  addition  to  the  client  area.  The  GetWindowDC  function  is  rarely  used.  If  you  want  to 
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experiment  with  it,  you  should  trap  WM_NCPAINT  (“nonclient  paint”)  messages,  which 
prevent  Windows  from  drawing  on  the  nonclient  area  of  the  window. 

The  BeginPaint,  GetDC \  and  GetWindowDC calls  obtain  a  device  context  associated 
with  a  particular  window.  You  can  also  obtain  a  device  context  for  the  entire  display  by 
calling  CreateDC : 

hdc  =  CreateDC  (IpszDriver,  IpszDevice,  IpszOutput,  lpData)  ; 

[other program  lines] 

DeleteDC  (hdc)  ; 

In  the  BLOWUP1  program  in  Chapter  4,  we  used  this  function  to  obtain  a  device  context 
handle  that  allowed  us  to  write  outside  our  window’s  client  area: 

hdc  =  CreateDC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 

Writing  outside  your  windows  is  generally  impolite,  but  it’s  convenient  for  some  unusual 
applications.  (Although  this  fact  is  undocumented,  you  can  also  retrieve  a  device  context 
for  the  entire  screen  by  calling  GetDC  with  a  NULL  parameter.) 

In  Chapter  15  we’ll  use  the  CreateDC  function  to  obtain  a  handle  to  a  printer  de¬ 
vice  context: 

hdcPri nter  =  CreateDC  ("IBMGRX" ,  "IBM  Graphics",  "LPT1:",  NULL)  ; 

Of  course,  we  won’t  include  the  names  of  specific  printers  in  our  programs.  Programs  can 
instead  obtain  this  information  from  WIN. INI. 

Sometimes  you  need  only  to  obtain  some  information  about  a  device  context  and  not 
to  do  any  drawing.  In  these  cases,  you  can  obtain  a  handle  to  an  “information  context” 
using  CreatelC.  The  parameters  are  the  same  as  for  the  CreateDC  function: 

hdclnfo  =  CreatelC  (IpszDriver,  IpszDevice,  IpszOutput,  lpData)  ; 

[other program  lines] 

DeleteDC  (hdclnfo)  ; 

You  can’t  write  to  the  device  using  this  information  context  handle.  We’ll  use  this  function 
in  the  DEVCAPS1  program  shown  later  in  this  chapter  to  obtain  an  information  context  for 
the  display  and  the  printer. 

In  the  GRAFMENU  program  in  Chapter  9,  we  obtained  a  memory  device  context  to 
manipulate  some  bitmaps.  A  memory  device  context  is  always  created  to  be  compatible 
with  an  existing  device  context: 

hdcMem  =  CreateCompatibl eDC  (hdc)  ; 

[other program  lines] 

DeleteDC  (hdcMem)  ; 

When  you  first  obtain  a  memory  device  context,  the  display  surface  that  it  represents  con¬ 
tains  exactly  1  pixel.  We’ll  work  more  with  memory  device  contexts  in  Chapter  13. 
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In  Chapter  13  we’ll  also  work  with  “metafiles.”  A  metafile  is  a  collection  of  GDI  calls 
encoded  in  binary  form.  You  can  create  a  metafile  by  obtaining  a  metafile  device  context: 

hdcMeta  =  CreateMetaFile  ( 1 pszFi 1 ename )  ; 

[other program  lines] 
hmf  =  Cl oseMetaFi 1 e  (hdcMeta)  ; 

During  the  time  that  the  metafile  device  context  is  valid,  any  GDI  calls  you  make  using 
hdcMeta  become  part  of  the  metafile.  When  you  call  CloseMetaFile ,  the  device  context 
handle  becomes  invalid.  The  function  returns  a  handle  to  the  metafile  ( hmf ). 

Getting  Device  Context  Information 

A  device  context  usually  refers  to  a  physical  display  device  such  as  a  video  display  or  a 
printer.  Often,  you  need  to  obtain  information  about  this  device,  including  the  size  of  the 
display  (in  terms  of  both  pixels  and  physical  dimensions)  and  its  color  capabilities.  You  can 
get  this  information  by  calling  the  GetDe viceCaps  (“get  device  capabilities”)  function: 

nValue  =  GetDeviceCaps  (hdc,  nlndex)  ; 

The  nlndex  parameter  is  1  of  28  identifiers  defined  in  WINDOWS.H.  For  instance,  the 
nlndex  HORZRES  causes  GetDeviceCaps  to  return  the  width  of  the  device  in  pixels;  a 
VERTRES  parameter  returns  the  height  of  the  device  in  pixels.  If  hdc  is  a  handle  to  a  screen 
device  context,  that’s  the  same  information  you  can  get  from  GetSystemMetrics.  If  hdc  is  a 
handle  to  a  printer  device  context,  then  GetDeviceCaps  returns  the  height  and  width  of  the 
printer  display  area  in  pixels. 

You  can  also  use  GetDeviceCaps  to  determine  the  device’s  capabilities  of  processing 
various  types  of  graphics.  This  is  unimportant  for  the  video  display,  but  it  becomes  very  im¬ 
portant  when  working  with  printers.  For  instance,  most  plotters  can’t  draw  bitmapped 
images — and  GetDeviceCaps  can  tell  you  that. 

The  DEVCAPS1  Program 

The  DEVCAPS1  program,  shown  in  Figure  11-1,  displays  all  the  information  available 
from  the  GetDeviceCaps  function  for  either  the  video  display  or  the  selected  printer.  (A 
second  version  of  this  program,  called  DEVCAPS2,  will  be  presented  in  Chapter  15.)  If  you 
change  the  current  printer  using  the  Windows  Control  Panel  program,  DEVCAPS1  updates 
the  printer  information. 
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DEVCAPS1.MAK 

# 

#  DEVCAPSl.MAK  make  file 

# 

devcapsl.exe  :  devcapsl.obj  devcaps.obj  devcapsl.def  devcapsl.res 
$(WINLINK)  devcapsl  devcaps,  devcapsl,  NUL,  $(WINLIB),  devcapsl 
rc  -t  devcapsl.res 

devcapsl.obj  :  devcapsl. c  devcapsl. h 
$(WINCC)  devcapsl. c 

devcaps.obj  :  devcaps. c 
$ ( W I NCC )  devcaps. c 

devcapsl.res  :  devcapsl. rc  devcapsl. h 
$ ( WI NRC )  devcapsl. rc 


DEVCAPS1.C 

/* . 

DEVCAPSl.C  -  Displays  Device  Capability  Information 
(c)  Charles  Petzold,  1992 

. */ 


#include  <windows.h> 

#include  <string.h> 

#include  "devcapsl. h" 

void  DoBasicInfo  (HDC,  HDC,  short,  short)  ;  //  in  DEVCAPS. C 

void  DoOtherlnfo  (HDC,  HDC,  short,  short)  ; 

void  DoBitCodedCaps  (HDC,  HDC,  short,  short,  short)  ; 

long  FAR  PASCAL  _export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "DevCaps"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


Figure  11-1.  The  DEVCAPS  1  program. 


(continued) 
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if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass.lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass. hbrBackground 
wndclass. IpszMenuName 
wndclass. IpszClassName 


CS_HREDRAW  !  CS.VREDRAW  ; 
WndProc  ; 


0  ; 

hlnstance  ; 

Loadlcon  (NULL.  IDI_APPLICATION)  ; 
LoadCursor  (NULL.  IDC_ARR0W)  • 
GetStockObject  (WHITE_BRUSH)  ; 
szAppName  ; 
szAppName  ; 


IRegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "Device  Capabilities", 
WS.OVERLAPPEDWINDOW, 
CW.USEDEFAULT,  CWJJSEDEFAULT, 
CW_USEDEFAULT,  CWJJSEDEFAULT, 
NULL,  NULL,  hlnstance.  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 


while  (GetMessage  (&msg,  NULL,  0,  0)) 
{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


HDC  GetPrinterIC  0 
{ 

char  szPrinter  [64]  ; 

char  *szDevice.  *szDriver,  *szOutput  ; 

GetProfileString  ("windows",  "device",  szPrinter,  64)  ; 

if  ((szDevice  =  strtok  (szPrinter.  ","  ))  && 

(szDriver  =  strtok  (NULL,  ",  "))  && 

(szOutput  =  strtok  (NULL,  ",  "))) 

return  CreateIC  (szDriver,  szDevice,  szOutput,  NULL)  ; 

return  NULL  ; 

} 


(continued) 
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long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  short  cxChar,  cyChar,  nCurrentDevice  =  IDM_SCREEN, 

nCurrentlnfo  =  IDM_BASIC  ; 

HDC  hdc,  hdclnfo  ; 

HMENU  hMenu  ; 

PAINTSTRUCT  ps  ; 

TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM_CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc.  GetStockObject  ( SYSTEM_FIXED_FONT) )  ; 

GetTextMetrics  (hdc,  &tm)  ; 

cxChar  =  tm.tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm.tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 
return  0  ; 

case  WM_COMMAND  : 

hMenu  =  GetMenu  (hwnd)  ; 


switch  (wParam) 

{ 

case  IDM_SCREEN  : 
case  I DM_PRI NTER  : 

CheckMenuItem  (hMenu,  nCurrentDevice,  MFJJNCHECKED)  ; 
nCurrentDevice  =  wParam  ; 


CheckMenuItem  (hMenu, 
InvalidateRect  (hwnd, 
return  0  ; 

case  IDM.BASIC  : 
case  IDM_0THER  : 
case  IDM.CURVE  : 
case  IDM.LINE  : 
case  IDM.POLY  : 
case  IDM_TEXT  : 

CheckMenuItem  (hMenu, 
nCurrentlnfo  =  wParam 
CheckMenuItem  (hMenu, 
InvalidateRect  (hwnd, 
return  0  ; 

} 

break  ; 


nCurrentDevice,  MF_CHECKED)  ; 
NULL,  TRUE)  ; 


nCurrentlnfo,  MFJJNCHECKED)  ; 

nCurrentlnfo,  MF.CHECKED)  ; 
NULL,  TRUE)  ; 


(continued) 
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case  WM.DEVMODECHANGE  : 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

case  WM_PA I  NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SelectObject  (hdc,  GetStockObject  ( SYSTEM_FI XED__F0NT ) )  ; 

if  (nCurrentDevice  ==  IDM.SCREEN) 

hdclnfo  =  CreateIC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 

else 

hdclnfo  =  GetPrinterIC  0  ; 

if  (hdclnfo) 

{ 

switch  (nCurrentlnfo) 

{ 

case  I DM_BAS I C  : 

DoBasicInfo  (hdc,  hdclnfo,  cxChar,  cyChar)  ; 
break  ; 

case  IDM_0THER  : 

DoOtherlnfo  (hdc,  hdclnfo,  cxChar,  cyChar)  ; 
break  ; 

case  IDM_CURVE  : 
case  IDM_LINE  : 
case  IDM.POLY  : 
case  IDM_TEXT  : 

DoBitCodedCaps  (hdc,  hdclnfo,  cxChar,  cyChar, 
nCurrentlnfo  -  IDM_CURVE)  ; 

break  ; 

} 

Del eteDC  (hdclnfo)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  lParam)  ; 
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DEVCAPS.C 


/* . . . . . 

DEVCAPS.C  -  Display  routines  for  DEVCAPS1  and  DEVCAPS2 
(c)  Charles  Petzold,  1992 


*/ 


//include  <windows.h> 

//include  <string.h> 

//include  <stdio.h> 

typedef  struct 

{ 

short  nMask  ; 
char  *szMask  ; 
char  *szDesc  ; 

} 

BITS  ; 

void  DoBasicInfo  (HDC  hdc,  HDC  hdclnfo,  short  cxChar,  short  cyChar) 

{ 

static  struct 

{ 


short  nlndex  ; 
char  *szDesc 
} 

info  []  = 

{ 

HORZSIZE, 

» 

"HORZSIZE 

Width  in  millimeters:", 

VERTSIZE, 

"VERTSIZE 

Height  in  millimeters:”, 

HORZRES, 

"HORZRES 

Width  in  pixels:". 

VERTRES, 

"VERTRES 

Height  in  raster  lines:", 

BITSPIXEL, 

"BITSPIXEL 

Color  bits  per  pixel :", 

PLANES, 

"PLANES 

Number  of  color  planes:", 

NUMBRUSHES, 

"NUMBRUSHES 

Number  of  device  brushes:", 

NUMPENS, 

"NUMPENS 

Number  of  device  pens:". 

NUMMARKERS, 

"NUMMARKERS 

Number  of  device  markers:", 

NUMFONTS, 

"NUMFONTS 

Number  of  device  fonts:". 

NUMCOLORS, 

"NUMCOLORS 

Number  of  device  colors:", 

PDEVICESIZE , 

"PDEVICESIZE 

Size  of  device  structure:", 

ASPECTX , 

"ASPECTX 

Relative  width  of  pixel:". 

ASPECTY , 

"ASPECTY 

Relative  height  of  pixel:", 

ASPECTXY , 

"ASPECTXY 

Relative  diagonal  of  pixel:" 

LOGPIXELSX, 

"LOGPIXELSX 

Horizontal  dots  per  inch:". 

LOGPIXELSY, 

"LOGPIXELSY 

Vertical  dots  per  inch:". 

SIZEPALETTE, 

"SIZEPALETTE 

Number  of  palette  entries:". 

NUMRESERVED, 

"NUMRESERVED 

Reserved  palette  entries:", 

COLORRES, 

}  ; 

"COLORRES 

Actual  color  resolution:" 

(continued) 
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char  szBuffer  [80]  ; 
short  i  ; 

for  ( i  =  0  ;  i  <  sizeof  info  /  sizeof  info  [0]  ;  i++) 
TextOut  (hdc,  cxChar,  (i  +  1)  *  cyChar,  szBuffer, 
sprintf  (szBuffer,  "%-40s%8d",  info[i].szDesc, 
GetDeviceCaps  (hdclnfo,  info[i].nIndex)))  ; 

} 


void  DoOtherlnfo  (HDC  hdc,  HDC  hdclnfo,  short  cxChar,  short  cyChar) 

{ 

static  BITS  clip  []  = 

{ 

CP_RECTANGLE,  ,,CP_RECTANGLE" ,  "Can  Clip  To  Rectangle:” 

}  ; 


static  BITS  raster  []  = 

{ 

RC.BITBLT,  "RC_BITBLT" ,  "Capable  of  simple  BitBlt:", 

RC_BANDING,  "RC_BANDING",  "Requires  banding  support:", 

RC_SCALING,  "RC_SCALING" ,  "Requires  scaling  support:", 

RC_BITMAP64,  "RC_BITMAP64" ,  "Supports  bitmaps  >64K:", 

RC_GDI20_OUTPUT,  "RC_GDI20_OUTPUT" ,  "Has  2.0  output  calls:", 
RC_DI_BITMAP,  "RC_DI_BITMAP" ,  "Supports  DIB  to  memory:", 

RC.PALETTE,  "RC.PALETTE" ,  "Supports  a  palette:", 

RC_DIBTODEV,  "RC.DIBTODEV",  "Supports  bitmap  conversion:", 

RC_B I GFONT ,  "RC_BIGFONT" ,  "Supports  fonts  >64K:", 

RC.STRETCHBLT,  "RC.STRETCHBLT" ,  "Supports  StretchBl t : " , 

RC.FLOODFILL,  "RC_FL00DFILL",  "Supports  FloodFIll :", 

RC.STRETCHDIB,  "RC.STRETCHDIB",  "Supports  StretchDIBits:" 

}  ; 


static  char  *szTech  []  =  {  "DT.PLOTTER  (Vector  plotter)", 

"DT.RASDISPLAY  (Raster  display)", 
"DT.RASPRINTER  (Raster  printer)", 
"DT.RASCAMERA  (Raster  camera)", 
"DT_CHARSTREAM  (Character-stream,  PLP)", 
"DT_METAFILE  (Metafile,  VDM)". 
"DT_DISPFILE  (Display-file)”  }  ; 

char  szBuffer  [80]  ; 

short  i  ; 


TextOut  (hdc,  cxChar,  cyChar,  szBuffer, 
sprintf  (szBuffer,  "%-24s%04XH", 

"DRIVERVERSION:",  GetDeviceCaps  (hdclnfo,  DRIVERVERSION) ) )  ; 

TextOut  (hdc,  cxChar,  2  *  cyChar,  szBuffer, 
sprintf  (szBuffer,  "%-24s%-40s". 

"TECHNOLOGY:",  szTech  [GetDeviceCaps  (hdclnfo,  TECHNOLOGY)]))  ; 
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TextOut  (hdc,  cxChar,  4  *  cyChar,  szBuffer, 

sprintf  (szBuffer,  "CLIPCAPS  (Clipping  Capabilities)"))  ; 

for  (i  =  0  ;  i  <  sizeof  clip  /  sizeof  clip  [0]  ;  i++) 

TextOut  (hdc,  9  *  cxChar,  (i  +  6)  *  cyChar,  szBuffer, 
sprintf  (szBuffer,  "%-16s%-28s  %3s". 
cl i p[i ] . szMask ,  cl i p[i ] .szDesc, 

GetDeviceCaps  (hdclnfo,  CLIPCAPS)  &  clip[i].nMask  ? 

"Yes"  :  "No"))  ; 

TextOut  (hdc,  cxChar,  8  *  cyChar,  szBuffer, 

sprintf  (szBuffer,  "RASTERCAPS  (Raster  Capabilities)"))  ; 

for  (i  =  0  ;  i  <  sizeof  raster  /  sizeof  raster  [0]  ;  i++) 

TextOut  (hdc,  9  *  cxChar,  (i  +  10)  *  cyChar,  szBuffer, 
sprintf  (szBuffer,  "%-16s%-28s  %3s". 

raster [i ] .szMask,  raster [i ] . szDesc, 

GetDeviceCaps  (hdclnfo,  RASTERCAPS)  &  raster[i] .nMask  ? 


void  DoBitCodedCaps  (HDC  hdc,  HDC  hdclnfo,  short  cxChar,  short  cyChar, 
short  nType) 

{ 

static  BITS  curves  []  = 


{ 

CC_C I RC  LES , 
CC.PIE, 
CC.CHORD, 
CC_ELLI PSES , 
CC_WIDE, 
CC_STYLED, 
CC__WI  DESTY  LED , 
CC_INTERIORS, 

}  ; 


"CC.CIRCLES", 
"CC_PIE" , 
"CC_CH0RD" , 
"CC_ELLI PSES" , 
"CC_WIDE”, 
"CC_STYLED" , 
"CC_WIDESTYLED", 
"CC.INTERIORS", 


"circles:", 

"pie  wedges:", 

"chord  arcs:", 

"ellipses:”, 

"wide  borders:", 

"styled  borders:", 

"wide  and  styled  borders:", 
"interiors:" 


static  BITS  lines  [1  = 


{ 

LC__P0LY  LI  NE , 

LC_MARKER, 

LC_POLYMARKER, 

LC_WIDE, 

LC_STYLED, 

LC_WIDESTYLED, 

LC_INTERIORS, 

}  ; 


"LC_POLYLINE" , 

"LC_MARKER", 

"LC_POLYMARKER", 

"LC_WIDE", 

"LC_STYLED", 

"LC.WIDESTYLED", 

"LC_INTERIORS" , 


"polyl ine:", 

"markers:", 

"polymarkers", 

"wide  lines:", 

"styled  lines:", 

"wide  and  styled  lines:", 
"interiors:" 
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static  BITS  poly  []  = 

{ 

PC.POLYGON,  "PC.POLYGON",  "alternate  fill  polygon:", 
PC_RECTANGLE,  "PC_RECTANGLE",  "rectangle:", 

PC_WINDP0LYG0N,  "PC.WINDPOLYGON”,  "winding  number  fill  polygon:", 

PC_SCAN  LINE,  "PC.SCANLINE",  "scanlines:". 

PC_WIDE,  ”PC_WIDE",  "wide  borders:", 

PC.STYLED,  "PC.STYLED".  "styled  borders:", 

PC_WIDESTYLED,  "PC_WIDESTYLED",  "wide  and  styled  borders:”, 
PC.INTERIORS,  "PC_INTERIORS".  "interiors:" 

}  : 

static  BITS  text  []  = 

{ 

TC_OP_CHARACTER,  "TC_OP_CHARACTER",  "character  output  precision:", 
TC_0P_STR0KE,  "TC_0P_STR0KE",  "stroke  output  precision:", 

TC_CP_STROKE,  "TC_CP_STROKE".  "stroke  clip  precision:", 

TC_CR_90,  "TC_CP_90",  "90-degree  character  rotation:", 

TC_CR_ANY ,  ”TC_CR_ANY",  "any  character  rotation:", 

TC_SF_X_YINDEP,  "TC_SF_X_YINDEP",  "scaling  independent  of  x  and  y:”, 
TC_SA_DOUBLE,  "TC_SA_DOUBLE",  "doubled  character  for  scaling:", 

TC_SA_INTEGER,  ”TC_SA_INTEGER",  "integer  multiples  for  scaling:", 

TC_SA_CONTIN,  "TC_SA_CONTIN",  "any  multiples  for  exact  scaling:", 
TC_EA_DOUBLE,  "TC_EA_DOUBLE”,  "double  weight  characters:", 

TC_IA_ABLE,  "TC_IA_ABLE".  "italicizing:", 

TC_UA_ABLE,  ”TC_UA_ABLE",  "underlining:", 

TC_S0_ABLE,  ”TC_S0_ABLE",  "strikeouts:", 

TC_RA_ABLE,  "TC_RA_ABLE",  "raster  fonts:", 

TC_VA_ABLE,  "TC_VA_ABLE",  "vector  fonts:" 

}  : 

static  struct 
{ 

short  nlndex  ; 
char  *szTitle  ; 

BITS  (*pbits)  []  ; 
short  nSize  ; 

} 

bitinfo  []  = 

{ 

CURVECAPS,  "CURVCAPS  (Curve  Capabilities)". 

(BITS  (*)[])  curves,  sizeof  curves  /  sizeof  curves  [0], 
LINECAPS,  "LINECAPS  (Line  Capabilities)", 

(BITS  (*)[])  lines,  sizeof  lines  /  sizeof  lines  [0], 
POLYGONALCAPS,  "POLYGONALCAPS  (Polygonal  Capabilities)”. 

(BITS  (*)[])  poly,  sizeof  poly  /  sizeof  poly  [0], 
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TEXTCAPS,  "TEXTCAPS  (Text  Capabilities)", 

(BITS  (*)[])  text,  sizeof  text  /  sizeof  text  [0] 

}  ; 

static  char  szBuffer  [80]  ; 

BITS  (*pbits)  []  =  bitinfo  [nType].pbits  ; 

short  nDevCaps  =  GetDeviceCaps  (hdclnfo,  bitinfo  [nType] .nlndex)  ; 

short  i  ; 

TextOut  (hdc,  cxChar,  cyChar,  bitinfo  [nType]. szTitle, 
strlen  (bitinfo  [nType]. szTitle))  ; 

for  ( i  =  0  ;  i  <  bitinfo  [nType] .nSize  ;  i++) 

TextOut  (hdc,  cxChar,  (i  +  3)  *  cyChar,  szBuffer, 
sprintf  (szBuffer,  "%-16s  Xs  %-32s  %3sM. 

(*pbits)[i].szMask,  "Can  do",  (*pbits)[i].szDesc, 
nDevCaps  &  (*pbits)[i].nMask  ?  "Yes"  :  "No"))  ; 

} 


DEVCAPS1.RC 

/* . 

DEVCAPSl.RC  resource  script 

— . . . */ 

^include  "devcapsl.h" 

DevCaps  MENU 
{ 

POPUP  "&Device" 

{ 

MENUITEM  "&Screen",  IDM.SCREEN,  CHECKED 

MENUITEM  "&Printer",  IDM.PRINTER 

} 

POPUP  "&Capabilities" 

{ 

MENUITEM  ”&Basic  Information",  IDM_BASIC,  CHECKED 

MENUITEM  "&0ther  Information".  IDM.OTHER 

MENUITEM  "&Curve  Capabilities",  IDM.CURVE 

MENUITEM  "&Line  Capabilities",  IDM.LINE 

MENUITEM  "&Polygonal  Capabi 1 i ties" . IDM_P0LY 
MENUITEM  "&Text  Capabilities",  IDM_TEXT 

} 

} 
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DEVCAPS1.H 


/* . 

DEVCAPSl. H  header  file 
. */ 


//def  i ne  IDM_SCREEN  1 
//define  IDM_PRINTER  2 

//define  IDM_BASIC  3 
//define  IDM_0THER  4 
//define  IDM.CURVE  5 
//define  IDM_LINE  6 
//define  IDM_P0LY  7 
//define  IDMJTEXT  8 


DEVCAPS1.DEF 


DEVCAPSl . DEF  module  definition  file 


NAME 


DEVCAPSl 


DESCRIPTION  displays  Device  Capability  Info  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  *  W INSTUB . EX  E 1 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


The  DEVCAPSl  Device  menu  lets  you  select  either  the  screen  or  the  printer.  Because  DEV¬ 
CAPSl  needs  only  to  obtain  information  about  this  device,  it  gets  a  handle  to  an  informa¬ 
tion  context  (using  the  CreateIC  function)  rather  than  to  a  device  context.  Getting  an 
information  context  handle  for  the  video  device  is  easy: 

HIC  =  CreateIC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 
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However,  an  information  context  handle  for  the  printer  requires  more  complex  code: 

HOC  GetPrinterIC  0 
{ 

char  szPrinter  [64]  ; 

char  *szDevice,  *szDriver,  *szOutput  ; 

GetProfi 1 eStri ng  ("windows",  "device",  "",  szPrinter,  64)  ; 


if  (NULL  !=  (szDevice  =  strtok  (szPrinter,  ","  ))  && 

NULL  !=  (szDriver  =  strtok  (NULL,  ",  "))  && 

NULL  !=  (szOutput  =  strtok  (NULL,  ",  "))) 

return  CreateIC  (szDriver,  szDevice,  szOutput,  NULL)  ; 


return  NULL  ; 

} 

The  selected  printer  is  listed  in  the  [windows]  section  of  the  WIN.INI  file  in  the 
following  format: 

device=device  name, driver  fi 1 ename.port 

For  an  IBM  Graphics  printer  connected  to  the  LPT1  printer  port,  the  WIN.INI  line  is: 

devi ce=IBM  Graphi cs , IBMGRX , LPT1 : 

IBM  Graphics  is  the  name  of  the  printer,  and  IBMGRX.DRV  is  the  name  of  the  driver  file. 

To  get  an  information  context  (or  device  context)  for  the  current  printer,  you  must 
first  obtain  the  character  string  following  device=  in  WIN.INI  by  using  the  GetProfileString 
function.  You  must  then  parse  this  string  into  the  three  components:  the  device  name,  the 
driver  filename,  and  the  port.  You  can  do  this  in  various  ways.  I  happened  to  use  the  C 
strtok  function,  which  is  designed  for  parsing  character  strings  separated  by  delimiters 
such  as  commas  and  spaces.  Note  that  the  device  name  itself  can  have  embedded  blanks. 

If  you’d  like  to  use  DEVCAPS1  to  examine  the  device  capabilities  of  other  printers, 
you  can  add  printer  driver  files  to  your  Windows  subdirectory  using  the  Control  Panel  pro¬ 
gram  and  then  select  each  of  these  printers,  one  by  one,  as  the  current  printer.  Specify  that 
the  port  the  printer  is  connected  to  is  “NONE."  An  advantage  of  CreateIC  over  CreateDC 
is  that  CreateDC  returns  a  device  context  handle  only  if  the  printer  is  attached  to  a  port, 
whereas  CreateIC  doesn’t  care  whether  the  printer  is  attached.  To  get  an  idea  of  the  range 
of  devices  you’ll  be  dealing  with,  you  might  want  to  obtain  the  GetDeviceCaps  information 
for  a  few  different  types  of  printers,  such  as  a  simple  nongraphics  printer  (the  “Generic/ 
Text  Only”  printer),  a  sophisticated  laser  printer  (the  Apple  LaserWriter  Plus),  and  a  plotter 
(the  Hewlett-Packard  ColorPro).  DEVCAPS1  intercepts  the  WM-DEVMODECHANGE 
message  that  Control  Panel  sends  to  all  applications  to  signal  that  the  current  printer  has 
been  changed. 
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The  Capabilities  menu  in  DEVCAPS1  lets  you  display  one  of  six  screens  that  show  the 
GetDeviceCaps  information.  Much  of  the  DEVCAPS1  code  is  dedicated  to  formatting  this 
information.  When  you  choose  the  Basic  Information  option  from  the  Capabilities  menu, 
the  most  important  information  is  displayed,  including  the  size  of  the  display,  the  number 
of  pure  colors  it  can  display,  and  the  organization  of  display  memory  into  color  planes  and 
color  bits  per  pixel.  Figure  11-2  shows  this  basic  information  for  a  VGA;  Figure  11-3  shows 
the  information  for  an  Apple  LaserWriter  Plus. 

When  you  choose  the  Other  Information  option  from  the  Capabilities  menu,  the  pro¬ 
gram  displays  the  type  of  device  (usually  “Raster  device,”  “Raster  printer,”  or  “Vector  plot¬ 
ter”)  and  gives  some  information  that  is  crucial  for  using  printers,  as  you’ll  discover  when 
you  come  to  Chapter  13.  Figure  11-4  shows  this  display  for  an  Apple  LaserWriter  Plus.  The 
RC_BITBLT  identifier  indicates  that  this  printer  can  accept  bitmaps;  text-only  printers  and 
plotters  cannot,  however,  which  means  that  some  GDI  functions  won’t  work  on  them.  The 
RC_BANDING  identifier  indicates  that  this  printer  does  not  require  “banding”  support, 
which  means  that  the  GDI  module  prints  to  the  printer  in  segments,  each  occupying  a 
small  section  of  the  page.  Again,  we’ll  explore  these  issues  further  in  Chapter  15. 


Device  Capabilities  _ DB 


Device  Capabilities 


HORZSIZE 

Width  in  millimeters: 

208 

UERTSIZE 

Height  in  millimeters: 

156 

HORZRES 

Width  in  pixels: 

640 

UERTRES 

Height  in  raster  lines: 

48  0 

BITSPIXEL 

Color  bits  per  pixel: 

1 

PLANES 

Number  of  color  planes: 

4 

NUMBRUSHES 

Number  of  device  brushes: 

-1 

NUMPENS 

Number  of  device  pens: 

80 

NUMMARKERS 

Number  of  device  markers: 

0 

NUMFONTS 

Number  of  device  fonts: 

0 

NUHC0L0RS 

Number  of  device  colors: 

16 

PDEUICESIZE 

Size  of  device  structure: 

35 

ASPECT* 

Relative  width  of  pixel: 

36 

ASPECTV 

Relative  height  of  pixel: 

36 

ASPECTXV 

Relative  diagonal  of  pixel: 

51 

LOGPIXELSX 

Horizontal  dots  per  inch: 

96 

LOGPIXELSV 

Uertical  dots  per  inch: 

96 

SIZEPALETTE 

Number  of  palette  entries: 

0 

NUMRESERUED 

Reserved  palette  entries: 

0 

COLORRES 

Actual  color  resolution: 

0 

File  Manager  Program 
Manager 


Figure  1 1  -2.  The  DEVCAPS1  display  invoked  by  choosing  Basic  Information 
from  the  Capabilities  menu  ivhen  the  specified  device  is  an  IBM  VGA. 
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|  Device  Capabilities 

HORZSIZE 

Width  in  millimeters : 

2  03 

UERTSIZE 

Height  in  millimeters: 

274 

HORZRES 

Width  in  pixels: 

2394 

UERTRES 

Height  in  raster  lines: 

3231 

BITSPIXEL 

Color  bits  per  pixel: 

1 

PLANES 

Number  of  color  planes: 

1 

NUMBRUSHES 

Number  of  deuice  brushes: 

17 

NUMPENS 

Number  of  deuice  pens: 

8 

NUMMARKERS 

Number  of  deuice  markers: 

0 

NUMFONTS 

Number  of  deuice  fonts: 

4 

NUMCOLORS 

Number  of  deuice  colors: 

2 

PDEUICESIZE 

Size  of  deuice  structure: 

738 

ASPECT* 

Relatiue  width  of  pixel: 

300 

ASPECTV 

Relatiue  height  of  pixel: 

300 

ASPECTXV 

Relatiue  diagonal  of  pixel: 

424 

LOGPIXELSX 

Horizontal  dots  per  inch: 

300 

LOGPIXELSV 

Uertical  dots  per  inch: 

300 

SIZEPALETTE 

Number  of  palette  entries: 

0 

NUMRESERUED 

Reserued  palette  entries: 

0 

COLORRES 

Actual  color  resolution: 

0 

File  Manager  Program 
Manager 


Figure  11-3.  The  DEVCAPS1  display  invoked  by  choosing  Basic  Information  from 
the  Capabilities  menu  when  the  specified  device  is  an  Apple  LaserWriter  Plus. 


mtmmsfmm 

|  Device  Capabilities 

DRIUERUERSION: 

03  00H 

TECHNOLOGV: 

DTRASPRINTER  (Raster  printer) 

CLIPCAPS  (Clipping  Capabilities) 

CPRECTANGLE 

Can  Clip  To  Rectangle: 

Ves 

RASTERCAPS  (Raster  Capabilities) 

RC  BITBLT 

Capable  of  simple  BitBlt: 

Ves 

RC  BANDING 

Requires  banding  support: 

No 

RC  SCALING 

Requires  scaling  support: 

No 

RC  BITMAP64 

Supports  bitmaps  >64K: 

Ves 

RC  GDI20  OUTPUT 

Has  2.0  output  calls: 

Ves 

RC  D I  BITMAP 

Supports  DIB  to  memory: 

No 

RC  PALETTE 

Supports  a  palette: 

No 

RC  DIBTODEU 

Supports  bitmap  conuersion: 

Ves 

RC  BIGFONT 

Supports  fonts  >64K: 

No 

RC  STRETCHBLT 

Supports  StretchBlt: 

Ves 

RC  FLOODFILL 

Supports  FloodFill: 

No 

RC  STRETCHDIB 

Supports  StretchDIBits: 

Ves 

Fite  Manager  Program 
Manager 


Figure  11-4.  The  DEVCAPS1  display  invoked  by  choosing  Other  Information  from 
the  Capabilities  menu  when  the  specified  device  is  an  Apple  LaserWriter  Plus. 
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The  other  menu  options  in  DEVCAPS1  display  curve,  line,  polygon,  and  text  capabili¬ 
ties.  The  information  displayed  indicates  the  type  of  graphics  and  text  manipulation  that 
the  device  driver  can  handle.  However,  this  information  is  much  more  important  to  Win¬ 
dows  itself  than  to  application  programs — if  the  driver  lacks  one  of  these  capabilities  and 
a  program  demands  it,  then  the  GDI  module  must  assume  the  task.  For  instance,  you  don’t 
have  to  check  to  see  if  your  printer  is  capable  of  drawing  ellipses  before  you  draw  an 
ellipse. 

The  information  that  you  can  obtain  from  GetDeviceCaps  using  the  CURVECAPS, 
LINECAPS,  POLYGONALCAPS,  and  TEXTCAPS  parameters  is  encoded  in  bits  in  the  return 
value.  WINDOWS.H  includes  identifiers  beginning  with  the  letters  CC,  LC,  PC,  and  TC  to 
help  you  mask  out  the  bits  you  want. 

The  Size  of  the  Device 

The  most  important  information  that  your  Windows  program  can  obtain  about  the  video 
device  from  GetDeviceCaps  is  the  size  of  the  display  (in  both  millimeters  and  pixels)  and 
the  display’s  pixel  aspect  ratio.  These  dimensions  can  help  in  scaling  images  to  be  dis¬ 
played.  To  give  you  some  idea  of  what  these  numbers  look  like,  the  table  below  presents 
information  from  GetDeviceCaps  for  four  common  IBM  video  adapters:  the  Color/Graphics 
Adapter  (CGA),  Enhanced  Graphics  Adapter  (EGA),  the  Video  Graphics  Array  (VGA),  and 
the  8514/A. 


GetDeviceCaps  Index 

CGA 

EGA 

VGA 

8514/A 

HORZSIZE  (width  in  mm) 

240 

240 

208 

280 

VERTSIZE  (height  in  mm) 

180 

175 

156 

210 

HORZRES  (pixel  width) 

640 

640 

640 

1024 

VERTRES  (pixel  height) 

200 

350 

480 

768 

ASPECTX  (horizontal) 

5 

38 

36 

10 

ASPECTY  (vertical) 

12 

48 

36 

10 

ASPECTXY  (diagonal) 

13 

61 

51 

14 

LOGPIXELSX  (x  pixels/inch) 

96 

96 

96 

120 

LOGPIXELSY  (y  pixels/inch) 

48 

72 

96 

120 

The  HORZSIZE  and  VERTSIZE  values  are  the  width  and  height  of  the  display  area  in 
millimeters.  Of  course,  the  Windows  driver  doesn’t  really  know  the  size  of  the  display  you 
have  attached  to  your  video  adapter.  These  dimensions  are  based  on  standard  display  sizes 
for  the  adapters. 

The  HORZRES  and  VERTRES  values  are  the  width  and  height  of  the  display  area  in 
pixels.  For  a  device  context  for  a  video  display,  these  are  the  same  values  as  those  returned 
from  GetSystemMetrics. 
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The  ASPECTX,  ASPECTY,  and  ASPECTXY  values  are  the  relative  width,  height,  and 
diagonal  size  of  each  pixel.  ASPECTXY  equals  the  square  root  of  the  sum  of  ASPECTX 
squared  and  ASPECTY  squared. 

The  LOGPIXELSX  and  LOGPIXELSY  values  are  the  number  of  pixels  per  a  horizontal 
and  a  vertical  “logical  inch.”  A  logical  inch  is  not  a  real  inch  (25.4  mm),  as  you  can  easily 
determine  by  performing  a  few  calculations  using  the  HORZSIZE,  VERTSIZE,  HORZRES, 
and  VERTRES  values.  These  LOGPIXELSX  and  LOGPIXELSY  values  require  a  little  ex¬ 
planation.  You  may  have  noticed  that  the  WRITE  program  and  some  other  Windows  pro¬ 
grams  display  a  ruler  that  isn’t  quite  right:  If  you  measure  the  ruler  as  displayed  on  a  VGA 
monitor,  you’ll  find  that  what  it  declares  as  1  inch  is  really  more  like  IVi  inches.  These  pro¬ 
grams  are  using  the  LOGPIXELSX  and  LOGPIXELSY  values  for  the  ruler.  If  WRITE  used 
actual  physical  dimensions,  normal  10-point  or  12-point  text  would  be  so  small  as  to  be 
nearly  illegible.  These  logical  dimensions  in  effect  blow  up  the  display  to  allow  an  ade¬ 
quate  size  for  displaying  text.  When  we  start  working  with  text  and  fonts  in  Chapter  14, 
we’ll  wrestle  again  with  this  problem.  It  affects  only  video  displays;  for  printers,  all  the 
dimensions  returned  from  GetDeviceCaps  are  consistent. 

Finding  Out  About  Color 

During  the  discussion  of  bitmaps  in  Chapter  8, 1  noted  the  two  ways  in  which  memory  in  a 
video  display  adapter  can  be  organized  for  color.  In  some  video  adapters,  memory  is 
organized  into  a  number  of  color  planes.  Within  a  plane,  each  bit  corresponds  to  a  single 
pixel  and  represents  a  particular  primary  color  (such  as  red,  green,  or  blue).  Other  video 
adapters  have  a  single  color  plane,  in  which  a  number  of  adjacent  bits  represent  the  color  of 
each  pixel. 

GetDeviceCaps  lets  you  determine  the  organization  of  memory  in  the  video  adapter 
and  the  number  of  colors  it  can  represent.  This  call  returns  the  number  of  color  planes: 

nPlanes  =  GetDeviceCaps  (hdc,  PLANES)  ; 

This  call  returns  the  number  of  color  bits  per  pixel: 

nBitsPixel  =  GetDeviceCaps  (hdc,  BITSPIXEL)  ; 

Most  graphics  display  devices  that  are  capable  of  color  use  either  multiple  color  planes  or 
multiple  color  bits  per  pixel,  but  not  both;  in  other  words,  one  of  these  calls  will  return  a 
value  of  1.  The  number  of  colors  that  can  be  rendered  on  the  video  adapter  can  be  calcu¬ 
lated  by  the  formula: 

nColors  =  1  <<  (nPlanes  *  nBitsPixel)  ; 

This  value  may  or  may  not  be  the  same  as  the  number  of  colors  obtainable  with  the 
NUMCOLORS  parameter: 

nColors  =  GetDeviceCaps  (hdc,  NUMCOLORS)  ; 


513 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


These  two  numbers  will  be  different  for  most  plotters.  For  a  plotter,  both  the  PLANES  and 
BITSPIXEL  values  will  equal  1,  but  the  NUMCOLORS  value  will  reflect  the  number  of  col¬ 
ored  pens  that  the  plotter  has.  For  monochrome  devices,  GetDeviceCaps  returns  a  2  for  the 
NUMCOLORS  parameter. 

The  two  values  can  also  be  different  for  video  adapters  that  support  loadable  color 
palettes  under  Windows  3  (such  as  the  IBM  8514/A  adapter).  The  8514/A  has  1  plane  and  8 
bits  per  pixel,  which  means  that  256  colors  are  possible.  GetDeviceCaps  with  the  NUM¬ 
COLORS  parameter  returns  the  number  of  colors  reserved  by  Windows  (20  in  the  case  of 
the  8514/A).  The  remaining  236  colors  can  be  set  by  a  Windows  program  using  the  palette 
manager. 

The  number  of  colors  returned  from  GetDeviceCaps  is  the  number  of  pure  colors  that 
the  device  can  display.  Windows  can  use  dithering  (which  involves  a  pixel  pattern  that 
combines  pixels  of  different  colors)  to  represent  colors  in  addition  to  the  pure  colors. 

A  color  is  usually  represented  by  an  unsigned  long  integer  with  3  bytes,  one  each  for 
the  intensity  of  red,  green,  and  blue.  (Chapters  5  and  6  discussed  this  subject  in  greater 
detail.)  You  can  determine  the  closest  pure  color  of  a  particular  color  value  by  calling 
GetNearestColor : 

rgbPureColor  =  GetNearestColor  (hdc,  rgbColor)  ; 

The  Device  Context  Attributes 

As  I  noted  above,  Windows  uses  the  device  context  to  store  “attributes”  that  govern  how 
the  GDI  functions  operate  on  the  display.  For  instance,  when  you  display  some  text  using 
the  TextOut  function,  you  don’t  have  to  specify  the  color  of  the  text  or  the  font.  Windows 
uses  the  device  context  to  obtain  this  information. 

When  a  program  obtains  a  handle  to  a  device  context,  Windows  creates  a  device  con¬ 
text  with  default  values  for  all  the  attributes.  The  device  context  attributes  are  shown  in  the 
following  table.  A  program  can  change  or  obtain  any  of  the  attributes. 


Device  Context 

Attribute 

Default 

Function(s)  to  Change 

Function  to  Get 

Mapping  mode 

MM -TEXT 

SetMapMode 

GetMapMode 

Window  origin 

(0,  0) 

SetWindoivOrg 

OffsetWindowOrg 

GetWindowOrg 

Viewport  origin 

(0,  0) 

SetViewportOrg 

Offset  ViewportOrg 

Get  ViewportOrg 

Window  extents 

(1, 1) 

SetWindowExt 

SetMapMode 

ScaleWindowExt 

GetWindowExt 

(continued) 
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continued 


Device  Context 

Attribute 

Default 

Function(s)  to  Change 

Function  to  Get 

Viewport 

a,  i) 

SetViewportExt 

Get  ViewportExt 

extents 

SetMapMode 

Scale  ViewportExt 

Pen 

BLACK_PEN 

SelectObject 

SelectObject 

Brush 

WHITE-BRUSH 

SelectObject 

SelectObject 

Font 

SYSTEM -FONT 

SelectObject 

SelectObject 

Bitmap 

None 

SelectObject 

SelectObject 

Current  pen 

(0,  0) 

MoveTo 

GetCurren  tPosition 

position 

LineTo 

Background 

mode 

OPAQUE 

SetBkMode 

GetBkMode 

Background 

color 

White 

SetBkColor 

GetBkColor 

Text  color 

Black 

SetTextColor 

GetTextColor 

Drawing  mode 

R2.COPYPEN 

SetROP2 

GetROP2 

Stretching  mode 

BLACK- 

ONWHITE 

SetPolyFillMode 

GetPolyFillMode 

Polygon  filling 
mode 

ALTERNATE 

SetPolyFillMode 

GetPolyFillMode 

Intercharacter 

0 

SetTextCharacterExtra 

GetTextCharacterExtra 

spacing 

Brush  origin 

(0,  0)  in  screen 
coordinates 

SetBrushOrg 

GetBrushOrg 

Clipping  region 

None 

SelectObject 

SelectClipRgn 

Inter sectClipRect 
OffsetClipRgn 

Excl  udeClipRect 

GetClipBox 

Saving  Device  Contexts 

Throughout  Section  IV,  you’ll  encounter  various  functions  to  change  the  device  context  at¬ 
tributes.  Normally,  Windows  creates  a  new  device  context  with  default  values  when  you 
call  GetDC or  BeginPaint.  All  changes  you  make  to  the  attributes  are  lost  when  the  device 
context  is  released  with  the  ReleaseDC or  the  EndPaint  call.  If  your  program  needs  to  use 
nondefault  device  context  attributes,  you’ll  have  to  initialize  the  device  context  every  time 
you  obtain  a  device  context  handle: 
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WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

[initialize  device  context  attributes] 

[paint  client  area  of  window] 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

Although  this  approach  is  generally  satisfactory,  you  might  prefer  that  changes  you 
make  to  the  device  context  attributes  be  saved  when  you  release  the  device  context  so  that 
they  will  be  in  effect  the  next  time  you  call  GetDC  or  BeginPaint.  You  can  accomplish 
this  by  including  the  CS_OWNDC  flag  as  part  of  the  window  class  when  you  register 
the  window  class: 

wndclass. style  =  CS_H REDRAW  !  CS_VREDRAW  !  CS.OWNDC  ; 

Now  each  window  that  you  create  based  on  this  window  class  will  have  its  own  private 
device  context  that  exists  until  the  window  is  destroyed.  When  you  use  the  CS_OWNDC 
style,  you  need  to  initialize  the  device  context  attributes  only  once,  perhaps  during  pro¬ 
cessing  of  the  WM-CREATE  message: 

WM_CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

[initialize  device  context  attributes] 

ReleaseDC  (hwnd,  hdc)  ; 

The  attributes  continue  to  be  valid  until  you  change  them. 

The  CS_OWNDC  style  affects  only  the  device  contexts  retrieved  from  GetDC  and 
BeginPaint  and  not  device  contexts  obtained  from  the  other  functions  (such  as  Get- 
WindowDC ).  The  CS-OWNDC  style  is  not  without  its  cost:  Windows  requires  about  800 
bytes  to  store  the  device  context  for  each  window  created  with  this  style.  Even  if  you  use 
CS_OWNDC,  you  must  still  release  the  device  context  before  exiting  the  window  function. 
You  can  also  use  the  CS-CLASSDC  style: 

wndclass. style  =  CS_H REDRAW  !  CS.VREDRAW  !  CS_CLASSDC  ; 

This  causes  each  window  class  to  have  its  own  device  context  that  is  shared  by  all  windows 
created  based  on  that  class — even  by  windows  created  in  other  instances  of  the  same  pro¬ 
gram.  Now  you  can  initialize  the  device  context  attributes  once  in  WinMain  following 
creation  of  the  first  window  based  on  that  window  class: 

if  ( IhPrevInstance) 

{ 

hdc  =  GetDC  (hwnd)  ; 

[initialize  device  context] 

ReleaseDC  (hwnd,  hdc)  ; 

} 
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In  general,  the  CS-CLASSDC  type  of  device  context  is  more  difficult  to  use  than  the 
CS-OWNDC  type,  because  any  changes  you  make  to  the  device  context  attributes  affect  all 
windows  in  all  instances  based  on  the  same  window  class.  This  could  have  some  strange 
effects,  particularly  if  you  use  a  customized  mapping  mode  (a  subject  coming  up  shortly) 
based  on  the  size  of  the  window. 

In  some  cases  you  might  want  to  change  certain  device  context  attributes,  do  some 
painting  using  the  changed  attributes,  and  then  revert  to  the  original  device  context.  To 
simplify  this  process,  you  save  the  state  of  a  device  context  by  calling: 

nSavedID  =  SaveDC  (hdc)  ; 

Now  you  change  some  attributes.  When  you  want  to  return  to  the  device  context  as  it 
existed  before  the  SaveDC  call,  you  use: 

RestoreDC  (hdc,  nSavedID)  ; 

You  can  call  SaveDC  any  number  of  times  before  calling  RestoreDC.  If  you  want  to  revert  to 
the  device  context  as  it  existed  before  the  last  SaveDC  call,  you  call: 

RestoreDC  (hdc,  -1)  ; 

THE  MAPPING  MODE 

One  device  context  attribute  that  affects  virtually  all  the  drawing  you  do  on  the  client  area 
is  the  “mapping  mode.”  Four  other  device  context  attributes — the  window  origin,  the 
viewport  origin,  the  window  extents,  and  the  viewport  extents — are  closely  related  to 
the  mapping  mode  attribute. 

Most  of  the  GDI  drawing  functions  require  coordinate  values  or  sizes.  For  instance, 
this  is  the  TextOut  function: 

TextOut  (hdc,  x,  y,  szBuffer,  nLength)  ; 

The  x  and  y  parameters  indicate  the  starting  position  of  the  text.  The  x  parameter  is  the 
position  on  the  horizontal  axis,  and  the  y  parameter  is  the  position  on  the  vertical  axis. 
Often  the  notation  (x,  y)  is  used  to  indicate  this  point. 

In  TextOut ,  as  in  virtually  all  GDI  functions,  these  coordinate  values  are  in  terms  of 
“logical  units.”  Windows  must  translate  the  logical  units  into  “device  units,”  or  pixels.  This 
translation  is  governed  by  the  mapping  mode,  the  window  and  viewport  origins,  and  the 
window  and  viewport  extents.  The  mapping  mode  also  implies  an  orientation  of  the  x-axis 
and  the  y- axis;  that  is,  it  determines  whether  values  of  x  increase  as  you  move  toward  the 
left  or  right  side  of  the  display  and  whether  values  of  y  increase  as  you  move  up  or  down 
the  display. 

Windows  defines  eight  mapping  modes.  These  are  listed  in  the  table  on  the  following 
page  using  the  WINDOW.H  identifiers. 
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Mapping  Mode 

Logical  Unit 

Increasing  Values 
x-axis  y -axis 

MM-TEXT 

Pixel 

Right 

Down 

MM-LOMETRIC 

0.1  mm 

Right 

Up 

MM-HIMETRIC 

0.01  mm 

Right 

Up 

MM-LOENGLISH 

0.01  in. 

Right 

Up 

MM-HIENGLISH 

0.001  in. 

Right 

Up 

MM-TWIPS* 

l/i44o  in. 

Right 

Up 

MM -ISOTROPIC 

Arbitrary  (x  =  y) 

Selectable 

Selectable 

MM-ANISOTROPIC 

Arbitrary  ( x\=  y ) 

Selectable 

Selectable 

*Twip  is  a  fabricated  word  meaning  “twentieth  of  a  point.”  A  point,  which  is  a  unit  of  measurement  for 
type,  is  approximately  Vn  inch  but  often  assumed  in  graphics  systems  such  as  GDI  to  be  exactly  Vn  inch.  A 
twip  is  Z20  point  and  hence  ‘/mo  inch. 

You  can  set  the  mapping  mode  by  using: 

SetMapMode  (hdc,  nMapMode)  ; 

where  nMapMode  is  one  of  the  eight  mapping  mode  identifiers.  You  can  obtain  the  current 
mapping  mode  by  calling: 

nMapMode  =  GetMapMode  (hdc)  ; 

The  default  mapping  mode  is  MM-TEXT.  In  this  mapping  mode,  logical  units  are  the 
same  as  physical  units,  which  allows  us  (or,  depending  on  your  perspective,  forces  us)  to 
work  directly  in  terms  of  pixels.  In  a  TextOut  cM  that  looks  like  this: 

TextOut  (hdc,  8,  16,  szBuffer,  nLength)  ; 

the  text  begins  8  pixels  from  the  left  of  the  client  area  and  16  pixels  from  the  top. 

If  the  mapping  mode  is  set  to  MM_LOENGLISH,  then  logical  units  are  in  terms  of 
hundredths  of  an  inch: 

SetMapMode  (hdc,  MM.LOENGLISH)  ; 

Now  the  TextOut  function  call  might  look  like  this: 

TextOut  (hdc,  50,  -100,  szBuffer,  nLength)  ; 

The  text  begins  0.5  inch  from  the  left  and  1  inch  from  the  top  of  the  client  area.  (The  reason 
for  the  negative  sign  in  front  of  the  jp-coordinate  will  become  clear  later,  when  I  discuss  the 
mapping  modes  in  more  detail.)  Other  mapping  modes  allow  programs  to  specify  coordi¬ 
nates  in  terms  of  millimeters,  a  printer’s  point  size,  or  an  arbitrarily  scaled  axis. 

If  you  feel  comfortable  working  in  terms  of  pixels,  you  don’t  need  to  use  any  mapping 
modes  except  the  default  MM -TEXT  mode.  If  you  need  to  display  an  image  in  actual  inch 
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or  millimeter  dimensions,  you  can  obtain  the  information  you  need  from  GetDeviceCaps 
and  do  your  own  scaling.  The  other  mapping  modes  are  simply  a  convenient  way  to  avoid 
doing  your  own  scaling. 

Regardless  of  the  mapping  mode,  all  coordinates  you  specify  in  Windows  functions 
must  be  signed  short  integers  in  the  range  32,767  through  -32,768.  Some  Windows  func¬ 
tions  that  use  coordinates  for  the  starting  point  and  ending  point  of  a  rectangle  also  require 
that  the  width  and  height  of  the  rectangle  be  32,767  or  less. 

Device  Coordinates  and  Logical  Coordinates 

You  may  ask:  If  I  use  the  MM_LOENGLISH  mapping  mode,  will  I  start  getting  WM_SIZE 
messages  in  terms  of  hundredths  of  an  inch?  Absolutely  not.  Windows  continues  to  use 
device  coordinates  for  all  messages  (such  as  WM_MOVE,  WM_SIZE,  and  WM- 
_MOUSEMOVE),  for  all  non-GDI  functions,  and  even  for  some  GDI  functions.  Think  of  it 
this  way:  The  mapping  mode  is  an  attribute  of  the  device  context,  so  the  only  time  the 
mapping  mode  comes  into  play  is  when  you  use  GDI  functions  that  require  a  handle  to  the 
device  context  as  one  of  the  parameters.  GetSystemMetrics  is  not  a  GDI  function,  so  it  will 
continue  to  return  sizes  in  terms  of  device  units,  which  are  pixels.  And  although  Get¬ 
DeviceCaps  is  a  GDI  function  that  requires  a  handle  to  a  device  context,  Windows  con¬ 
tinues  to  return  device  units  for  the  HORZRES  and  VERTRES  indexes,  because  one  of  the 
purposes  of  this  function  is  to  provide  a  program  with  the  size  of  the  device  in  pixels. 

However,  the  values  in  the  TEXTMETRIC  structure  that  you  obtain  from  the  GetText- 
Metrics  call  are  in  terms  of  logical  units.  If  the  mapping  mode  is  MM_LOENGLISH  at  the 
time  the  call  is  made,  GetTextMetrics  provides  character  widths  and  heights  in  terms  of 
hundredths  of  an  inch.  When  you  call  GetTextMetrics  tor  information  about  the  height  and 
width  of  characters,  the  mapping  mode  should  be  set  to  the  same  mapping  mode  that  you’ll 
be  using  when  you  draw  text  based  on  these  sizes.  As  I  cover  the  various  GDI  functions  in 
this  and  subsequent  chapters,  I’ll  note  whether  they  use  device  coordinates  or  logical 
coordinates. 

The  Device  Coordinate  Systems 

Windows  maps  logical  coordinates  specified  in  GDI  functions  to  device  coordinates. 
Before  we  discuss  the  logical  coordinate  systems  used  with  the  various  mapping  modes, 
let’s  examine  the  different  device  coordinate  systems  that  Windows  defines  for  the  video 
display  area.  Although  we  have  been  working  mostly  within  the  client  area  of  our  window, 
Windows  uses  two  other  device  coordinate  areas  at  various  times.  In  all  device  coordinate 
systems,  units  are  in  terms  of  pixels.  Values  on  the  horizontal,  or  x,  axis  increase  from  left 
to  right,  and  values  on  the  vertical,  or  y,  axis  increase  from  top  to  bottom. 

When  we  use  the  entire  screen,  we  are  working  in  terms  of  “screen  coordinates.” 
The  upper  left  corner  of  the  screen  is  the  point  (0,  0).  Screen  coordinates  are  used  in  the 
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WM-MOVE  message  (for  nonchild  windows)  and  in  the  following  Windows  functions: 
CreateWindow  and  MoveWindow  (both  for  nonchild  windows),  GetMessagePos,  GetCur- 
sorPos ,  SetCursorPos ,  GetWindowRect,  WindowFromPoint,  and  SetBrushOrg.  These  are 
generally  either  functions  that  don’t  have  a  window  associated  with  them  (such  as  the 
two  cursor  functions)  or  functions  that  must  move  (or  find)  a  window  based  on  a  screen 
point.  If  you  use  CreateDC  with  a  DISPLAY  parameter  to  obtain  a  device  context  for  the 
entire  screen,  then  logical  coordinates  specified  in  GDI  calls  will  be  mapped  to  screen 
coordinates. 

“Whole-window  coordinates”  refer  to  a  program’s  entire  window,  including  the  cap¬ 
tion  bar,  menu,  scroll  bars,  and  window  frame.  For  a  normal  window,  the  point  (0,  0)  is  the 
upper  left  corner  of  the  sizing  border.  Whole-window  coordinates  are  rare  in  Windows,  but 
if  you  obtain  a  device  context  from  GetWindowDC \  logical  coordinates  in  GDI  functions 
will  be  mapped  to  whole-window  coordinates. 

The  third  device  coordinate  system — the  one  we’ve  been  working  with  the  most — 
uses  “client-area  coordinates.”  The  point  (0,  0)  is  the  upper  left  corner  of  the  client  area. 
When  you  obtain  a  device  context  using  GetDC  or  BeginPaint ,  logical  coordinates  in  GDI 
functions  are  translated  to  client-area  coordinates. 

You  can  convert  client-area  coordinates  to  screen  coordinates  and  vice  versa  using 
the  functions  ClientToScreen  and  ScreenToClient.  You  can  also  obtain  the  position  and 
size  of  the  whole  window  in  terms  of  screen  coordinates  using  the  GetWindowRect  func¬ 
tion.  These  three  functions  provide  enough  information  to  translate  from  any  one  device 
coordinate  system  to  any  other. 

The  Viewport  and  the  Window 

The  mapping  mode  defines  how  Windows  maps  logical  coordinates  that  are  specified  in 
GDI  functions  to  device  coordinates,  where  the  particular  device  coordinate  system  de¬ 
pends  on  the  function  you  use  to  obtain  the  device  context.  To  continue  our  discussion  of 
the  mapping  mode,  we  need  some  additional  terminology:  The  mapping  mode  is  said 
to  define  the  mapping  of  the  “window”  (logical  coordinates)  to  the  “viewport”  (device 
coordinates). 

The  use  of  the  words  window  and  viewport  is  unfortunate.  In  other  graphics  inter¬ 
face  languages,  viewport  often  implies  a  clipping  region.  We’ve  been  using  the  word  win¬ 
dow  to  talk  about  the  area  that  a  program  occupies  on  the  screen.  We’ll  have  to  put  aside 
our  preconceptions  about  these  words  during  this  discussion. 

The  “viewport”  is  in  terms  of  device  coordinates  (pixels).  Most  often,  the  viewport  is 
the  same  as  the  client  area,  but  it  can  also  refer  to  whole-window  coordinates  or  screen 
coordinates  if  you’ve  obtained  a  device  context  from  GetWindowDC  or  CreateDC.  The 
point  (0,  0)  is  the  upper  left  corner  of  the  client  area  (or  the  whole  window  or  the  screen). 
Values  of  x  increase  to  the  right,  and  values  of  y  increase  going  down. 
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The  “window”  is  in  terms  of  logical  coordinates,  which  may  be  pixels,  millimeters, 
inches,  or  any  other  unit  you  want.  You  specify  logical  window  coordinates  in  the  GDI 
functions. 

For  all  mapping  modes,  Windows  translates  window  (logical)  coordinates  to  view¬ 
port  (device)  coordinates  by  the  use  of  two  formulas: 

xViewExt 

xViewport  =  ( xWindow  -  xWinOrg)  *  xWinExt  +  x^ew(^r§ 


vViewExt 

yViewport  =  (yWindow  -  yWinOrg)  *  yWinExt  +  yView0rE 

where  {xWindow,  yWindow)  is  a  logical  point  to  be  translated,  and  (, xViewport ,  yViewport ) 
is  the  translated  point  in  device  coordinates.  If  the  device  coordinates  are  client-area  coor¬ 
dinates  or  whole-window  coordinates,  then  Windows  must  also  translate  these  device 
coordinates  to  screen  coordinates  before  drawing  an  object. 

These  formulas  use  two  points  that  specify  an  “origin”  of  the  window  and  the 
viewport:  ( xWinOrg ,  yWinOrg )  is  the  window  origin  in  logical  coordinates;  ( xViewOrg , 
yViewOrg. )  is  the  viewport  origin  in  device  coordinates.  In  the  default  device  context,  these 
two  points  are  set  to  (0,  0),  but  they  can  be  changed.  The  formulas  imply  that  the  logical 
point  ( xWinOrg ,  yWinOrg )  is  always  mapped  to  the  device  point  ( xViewOrg, ,  yViewOrg). 

The  formulas  also  use  two  points  that  specify  “extents”:  ( xWinExt ,  yWinExf)  is  the 
window  extent  in  logical  coordinates;  ( xViewExt ,  yViewExt )  is  the  viewport  extent  in  de¬ 
vice  coordinates.  In  most  mapping  modes,  the  extents  are  implied  by  the  mapping  mode 
and  cannot  be  changed.  Each  extent  means  nothing  by  itself,  but  the  ratio  of  the  viewport 
extent  to  the  window  extent  is  a  scaling  factor  for  converting  logical  units  to  device  units. 
The  extents  can  be  negative:  This  implies  that  values  on  the  logical  x-axis  don’t  necessarily 
have  to  increase  to  the  right  and  that  values  on  the  logical  y- axis  don’t  necessarily  have  to 
increase  going  down. 

Windows  can  also  translate  from  viewport  (device)  coordinates  to  window  (logical) 
coordinates: 

xWinExt 

xWindow  =  (xViewport  -  xViewOrg)  *  xViewExt  +  xWinOrg 

yWindow  =  (yViewport  -  yViewOrg)  *  ^VlewExt  +  yWinOrg 

Windows  provides  two  functions  that  let  you  convert  device  points  to  logical  points 
and  vice  versa  within  a  program.  The  following  function  converts  device  points  to  logical 
points: 

DPtoLP  (hdc,  IpPoints,  nNumber)  ; 


521 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


The  variable  IpPoints  is  a  long  pointer  to  an  array  of  POINT  structures,  and  nNumber  is 
the  number  of  points  to  be  converted.  You’ll  find  this  function  useful  for  converting  the 
size  of  the  client  area  obtained  from  GetClientRect  (which  is  always  in  terms  of  device 
units)  to  logical  coordinates: 

GetClientRect  (hwnd,  &rect)  ; 

DPtoLP  (hdc,  ( LPPOINT)  &rect,  2)  ; 

This  function  converts  logical  points  to  device  points: 

LPtoDP  (hdc,  IpPoints,  nNumber)  ; 

Working  with  MM.TEXT 

For  the  MM_TEXT  mapping  mode,  the  default  origins  and  extents  are  shown  below: 


Window  origin: 

(0,  0) 

Can  be  changed 

Viewport  origin: 

(0,  0) 

Can  be  changed 

Window  extent: 

(1,1) 

Cannot  be  changed 

Viewport  extent: 

(1,1) 

Cannot  be  changed 

The  ratio  of  the  viewport  extent  to  the  window  extent  is  1,  so  no  scaling  is  performed  be¬ 
tween  logical  coordinates  and  device  coordinates.  The  formulas  shown  on  the  preceding 
page  reduce  to  these: 

xViewport  =  xWindow  -  xWinOrg  +  xViewOrg 
yViewport  =  yWindow  -  yWinOrg  +  yViewOrg 

This  mapping  mode  is  called  a  “text”  mapping  mode  not  because  it’s  most  suitable 
for  text  but  because  of  the  orientation  of  the  axes.  We  read  text  from  left  to  right  and  top  to 
bottom,  and  MM -TEXT  defines  values  on  the  axes  to  increase  the  same  way: 


- ► 

+x 


r 


Windows  provides  the  functions  SetViewportOrg  and  SetWindowOrg  for  changing  the 
viewport  and  window  origins.  These  functions  have  the  effect  of  shifting  the  axis  so  that 
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the  logical  point  (0,  0)  no  longer  refers  to  the  upper  left  corner.  Generally,  you’ll  use  either 
SetViewportOrg  or  SetWindowOrg  but  not  both. 

Here’s  how  these  functions  work:  If  you  change  the  viewport  origin  to  ( xViewOrg , 
yViewOrg ),  then  the  logical  point  (0,  0)  will  be  mapped  to  the  device  point  ( xViewOrg , 
yViewOrg).  If  you  change  the  window  origin  to  ( xWinOrg ,  yWinOrg ),  then  the  logical 
point  ( xWinOrg ,  yWinOrg )  will  be  mapped  to  the  device  point  (0,  0),  which  is  the  upper 
left  corner.  Regardless  of  any  changes  you  make  to  the  window  and  viewport  origins,  the 
device  point  (0,  0)  is  always  the  upper  left  corner  of  the  client  area. 

For  instance,  suppose  your  client  area  is  cxClient  pixels  wide  and  cyClient  pixels 
high.  If  you  want  to  define  the  logical  point  (0,  0)  to  be  the  center  of  the  client  area,  you  can 
do  so  by  calling: 

SetViewportOrg  (hdc,  cxClient  /  2,  cyClient  /  2)  ; 

The  arguments  to  SetViewportOrg  are  always  in  terms  of  device  units.  The  logical  point 
(0,  0)  will  now  be  mapped  to  the  device  point  {cxClient/ 2,  cyClient/ 2).  Now  you  use  your 
client  area  as  if  it  had  the  following  coordinate  system: 


i 

-x 

+ 

>< 

r 

> 

+y 

r 

The  logical  x-axis  ranges  from  -cxClient  / 2  to  +cxClient  / 2,  and  the  logical  y- axis  ranges 
from  -cyClient  / 2  to  +cyClient  /2.  The  lower  right  corner  of  the  client  area  is  the  logical 
point  {cxClient / 2,  cyClient / 2/  If  you  want  to  display  text  starting  at  the  upper  left  corner 
of  the  client  area,  which  is  the  device  point  (0,  0),  you  need  to  use  negative  coordinates: 

TextOut  (hdc,  -cxClient  /  2,  -cyClient  /  2,  "Hello",  5)  ; 

You  can  achieve  the  same  result  with  SetWindowOrg  as  you  did  with  SetViewportOrg : 

SetWindowOrg  (hdc,  -cxClient  /  2,  -cyClient  /  2)  ; 

The  arguments  to  SetWindowOrg  are  always  in  terms  of  logical  units.  After  this  call,  the 
logical  point  {-cxClient  / 2,  -cyClient  / 2)  is  mapped  to  the  device  point  (0,  0),  the  upper 
left  corner  of  the  client  area. 
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What  you  probably  don’t  want  to  do  (unless  you  know  what’s  going  to  happen)  is  to 
use  both  functions  together: 

SetViewportOrg  (hdc,  cxClient  /  2,  cyClient  /  2)  ; 

SetWindowOrg  (hdc,  -cxClient  /  2,  -cyClient  /  2)  ; 

This  means  that  the  logical  point  {-cxClient  / 2,  -cyClient  / 2)  is  mapped  to  the  device 
point  {cxClient / 2,  cyClient / 2),  giving  you  a  coordinate  system  that  looks  like  this: 


-rt 


You  can  obtain  the  current  viewport  and  window  origins  from  these  functions: 
dwViewOrigin  =  GetViewportOrg  (hdc)  ; 
dwWindowOrigin  =  GetWindowOrg  (hdc)  ; 

Both  functions  return  DWORDs  (unsigned  longs).  The  x-origin  is  in  the  low  word  and  the 
jp-origin  is  in  the  high  word.  You  can  use  the  LOWORD  and  HIWORD  macros  to  extract 
these  two  values  from  the  DWORD.  The  values  returned  from  GetViewportOrg  are  in  de¬ 
vice  coordinates;  the  values  returned  from  GetWindowOrg  are  in  logical  coordinates. 

You  might  want  to  change  the  viewport  or  window  origin  to  shift  display  output 
within  the  client  area  of  your  window — for  instance,  in  response  to  scroll  bar  input  from 
the  user.  Changing  the  viewport  or  window  origin  doesn’t  shift  the  display  output  immedi¬ 
ately,  of  course.  You  change  the  origin  and  then  repaint  the  display.  For  instance,  in  the 
SYSMETS2  program  in  Chapter  2,  we  used  the  nVscrollPosv alue  (the  current  position  of 
the  vertical  scroll  bar)  to  adjust  the  jy- coordinates  of  the  display  output: 

case  WM_PA I  NT  : 

BeginPaint  (hwnd,  &ps)  ; 

for  (i  =  0  ;  i  <  NUMLINES  ;  1++) 

{ 

y  =  cyChar  *  (1  -  nVscrollPos  +  i)  ; 

[display  text] 

} 

EndPaint  (hwnd,  &ps)  ; 

return  0  ; 
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We  can  achieve  the  same  result  using  SetWindowOrg : 

case  WM_PAI NT  : 

BeginPaint  (hwnd,  &ps)  ; 

SetWindowOrg  (ps.hdc,  0,  cyChar  *  nVscrol 1 Pos )  ; 

for  (i  =  0  ;  i  <  NUMLINES  ;  i++) 

{ 

y  =  cyChar  *  (1  +  i )  ; 

[display  text] 

) 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

Now  the  calculation  of  the  jy-coordinate  for  the  TextOut  functions  doesn’t  require  the 
nVscrollPos  value.  This  means  you  can  put  the  text  output  functions  in  a  subroutine  and 
not  have  to  pass  the  nVscrollPos  value  to  the  subroutine,  because  we  adjust  the  display  of 
the  text  by  changing  the  window  origin. 

If  you  have  some  experience  working  with  rectangular  (or  Cartesian)  coordinate  sys¬ 
tems,  moving  the  logical  point  (0,  0)  to  the  center  of  the  client  area  as  we  did  earlier  may 
have  seemed  a  reasonable  action.  However,  there’s  a  slight  problem  with  the  MM_TEXT 
mapping  mode:  Usually  a  Cartesian  coordinate  system  defines  values  on  the  y- axis  to  in¬ 
crease  as  you  move  up  the  axis,  whereas  MM_TEXT  defines  the  values  to  increase  as  you 
move  down.  In  this  sense,  MM -TEXT  is  an  oddity,  and  these  next  five  mapping  modes  do 
it  correctly. 

The  “Metric”  Mapping  Modes 

Windows  includes  five  mapping  modes  that  express  logical  coordinates  in  physical  mea¬ 
surements.  Because  logical  coordinates  on  the  x-axis  and  y- axis  are  mapped  to  identical 
physical  units,  these  mapping  modes  help  you  to  draw  round  circles  and  square  squares. 

The  five  “metric”  mapping  modes  are  arranged  below  in  order  of  lowest  precision  to 
highest  precision.  The  two  columns  at  the  right  show  the  size  of  the  logical  units  in  terms 
of  inches  (in.)  and  millimeters  (mm)  for  comparison: 


Mapping  Mode 

Logical  Unit 

Inch 

Millimeter 

MM-LOENGLISH 

0.01  in. 

0.01 

0.254 

MM-LOMETRIC 

0.1  mm 

0.00394 

0.1 

MM-HIENGLISH 

0.001  in. 

0.001 

0.0254 

MM-TWIPS* 

V\aaq  in. 

0.000694 

0.0176 

MM-HIMETRIC 

0.01  mm 

0.000394 

0.01 

*A  twip  equals  Vio  point  (which  itself  equals  Z12  inch)  and  hence  Via 0  inch. 
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To  give  you  an  idea  of  how  the  MM -TEXT  mode  fits  in  with  these  resolutions,  on  a 
standard  VGA  display  each  pixel  is  0.325  mm  wide  and  high,  so  VGA  device  coordinates 
are  coarser  than  the  logical  coordinates  for  any  of  the  metric  mapping  modes. 

On  a  300-dots-per-inch  laser  printer,  each  pixel  is  0.0033  inch — a  higher  resolution 
than  MM-LOENGLISH  and  MM-LOMETRIC  but  not  as  high  as  MM-HIENGLISH,  MM- 
_TWIPS,  or  MM-HIMETRIC. 

The  default  origins  and  extents  are  shown  below: 


Window  origin: 

(0,  0) 

Can  be  changed 

Viewport  origin: 

(0,  0) 

Can  be  changed 

Window  extent: 

(?,  ?) 

Cannot  be  changed 

Viewport  extent' 

(?,?) 

Cannot  be  changed 

The  window  and  viewport  extents  depend  on  the  mapping  mode  and  the  aspect  ratio  of 
the  device.  As  I  mentioned  earlier,  the  extents  aren’t  important  by  themselves  but  take  on 
meaning  only  when  expressed  as  ratios.  Here  are  the  translation  formulas  again: 


xViewport  =  (xWindow  -  xWinOrg) 


xViewExt 

xWinExt 


+  xViewOrg 


yViewport  =  (yWindow  -  yWinOrg)  *  ^^^Ext  +  yView°r8 
For  MM_LOENGLISH,  for  instance,  Windows  calculates  the  extents  to  be  the  following: 


xViewExt 

xWinExt 


=  number  of  horizontal  pixels  in  0.01  in. 


vViewExt 

~yWfnExF  =  number  °f  vertical  pixels  in  0.01  in. 

For  many  display  devices  (such  as  the  VGA),  this  ratio  will  be  less  than  1.  Because  Windows 
works  entirely  with  integers,  the  use  of  a  ratio  rather  than  an  absolute  scaling  factor  is 
necessary  to  reduce  loss  of  precision  when  converting  logical  and  device  coordinates. 

Notice  the  negative  sign  in  front  of  the  ratio  of  extents  for  the  vertical  axis.  This  nega¬ 
tive  sign  changes  the  orientation  of  the  y- axis.  For  these  five  mapping  modes,  ^values  in¬ 
crease  as  you  move  up  the  device.  The  default  window  and  viewport  origins  are  (0,  0).  This 
fact  has  an  interesting  implication.  When  you  first  change  to  one  of  these  five  mapping 
modes,  the  coordinate  system  looks  like  this: 


526 


Chapter  11:  An  Introduction  to  GDI 


The  only  way  you  can  display  anything  in  the  client  area  is  to  use  negative  values  of  y. 
For  instance,  this  code: 

SetMapMode  (hdc,  MM.LOENGLISH)  ; 

TextOut  (hdc.  100.  -100.  "Hello".  5)  ; 

displays  Hello  1  inch  from  the  top  and  left  edges  of  the  client  area. 

To  preserve  your  sanity,  you’ll  probably  want  to  avoid  this.  One  solution  is  to  set  the 
logical  (0,  0)  point  to  be  the  lower  left  corner  of  the  client  area.  Assuming  that  cyClient  is 
the  height  of  the  client  area  in  pixels,  you  can  do  this  by  calling  SetViewportOrg : 

SetViewportOrg  (hdc,  0,  cyClient)  ; 

Now  the  coordinate  system  looks  like  this: 


Alternatively,  you  can  set  the  logical  (0,  0)  point  to  the  center  of  the  client  area: 
SetViewportOrg  (hdc,  cxClient  /  2,  cyClient  /  2)  ; 
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The  coordinate  system  looks  like  this: 


+ 

* 

1 

+*  * 

> 

-y 

f 

Now  we  have  a  real  four-quadrant  Cartesian  coordinate  system  with  equal  logical  units  on 
the  x-axis  and  y-axis  in  terms  of  inches,  millimeters,  or  twips. 

You  can  also  use  the  SetWindowOrg  function  to  change  the  logical  (0,  0)  point,  but 
the  task  is  a  little  more  difficult  because  the  parameters  to  SetWindowOrg  have  to  be  in 
logical  coordinates.  You  would  first  need  to  convert  ( cxClient ,  cyClient )  to  a  logical  coor¬ 
dinate  using  the  DPtoLP  function.  Assuming  that  the  variable  pt  is  a  structure  of  type 
POINT,  this  code  changes  the  logical  (0,  0)  point  to  the  center  of  the  client  area: 

pt.x  =  cxClient  ; 

pt.y  =  cyClient  ; 

DPtoLP  (hdc,  Apt.  1)  ; 

SetWindowOrg  (hdc.  -pt.x  /  2.  -pt.y  /  2)  ; 

The  “Roll  Your  Own”  Mapping  Modes 

The  two  remaining  mapping  modes  are  called  MM_ISOTROPIC  and  MM -ANISOTROPIC. 
These  are  the  only  two  mapping  modes  for  which  Windows  lets  you  change  the  viewport 
and  window  extents,  which  means  that  you  can  change  the  scaling  factor  that  Windows 
uses  to  translate  logical  and  device  coordinates.  The  word  isotropic  means  “equal  in  all 
directions”;  anisotropic  is  the  opposite — “not  equal.”  Like  the  metric  mapping  modes 
shown  earlier,  MM -ISOTROPIC  uses  equally  scaled  axes.  Logical  units  on  the  x-axis  have 
the  same  physical  dimensions  as  logical  units  on  the  y-axis.  This  helps  when  you  need  to 
create  images  that  retain  the  correct  aspect  ratio  regardless  of  the  aspect  ratio  of  the 
display  device. 

The  difference  between  MM -ISOTROPIC  and  the  metric  mapping  modes  is  that  with 
MM -ISOTROPIC  you  can  control  the  physical  size  of  the  logical  unit.  If  you  want,  you  can 
adjust  the  physical  size  of  the  logical  unit  based  on  the  size  of  the  client  area  so  that  the  im¬ 
ages  you  draw  are  always  contained' within  the  client  area,  shrinking  and  expanding  ap¬ 
propriately.  For  instance,  the  CLOCK  program  included  with  Windows  is  an  example  of  an 
isotropic  image.  The  clock  is  always  round.  As  you  size  the  window,  the  image  is  resized 


528 


Chapter  11:  An  Introduction  to  QDI 


appropriately.  A  Windows  program  can  handle  the  resizing  of  an  image  entirely  through 
adjusting  the  window  and  viewport  extents.  The  program  can  then  use  the  same  logical 
units  in  the  drawing  functions  regardless  of  the  size  of  the  window. 

Sometimes  the  MM-TEXT  and  the  “metric”  mapping  modes  are  called  “fully  con¬ 
strained”  mapping  modes.  This  means  that  you  cannot  change  the  window  and  viewport 
extents  and  the  way  Windows  scales  logical  coordinates  to  device  coordinates.  MM- 
-ISOTROPIC  is  a  “partly  constrained”  mapping  mode.  Windows  allows  you  to  change  the 
window  and  viewport  extents,  but  it  adjusts  them  so  that  x  and  y  logical  units  represent  the 
same  physical  dimensions.  The  MM -ANISOTROPIC  mapping  mode  is  “unconstrained.” 
You  can  change  the  window  and  viewport  extents,  and  Windows  doesn’t  adjust  the  values. 

The  MM-ISOTROPIC  mapping  mode 

The  MM -ISOTROPIC  mapping  mode  is  ideal  for  using  arbitrary  axes  while  preserving 
equal  logical  units  on  the  two  axes.  Rectangles  with  equal  logical  widths  and  heights  are 
displayed  as  squares.  Ellipses  with  equal  logical  widths  and  heights  are  displayed  as 
circles. 

When  you  first  set  the  mapping  mode  to  MM -ISOTROPIC,  Windows  uses  the  same 
window  and  viewport  extents  that  it  uses  with  MM-LOMETRIC.  (Don’t  rely  on  this  fact, 
however.)  The  difference  is  that  you  can  now  change  the  extents  to  suit  your  preferences 
by  calling  SetWindowExt and  SetViewportExt.  Windows  will  then  adjust  the  extents  so  that 
the  logical  units  on  both  axes  represent  equal  physical  distances. 

Generally,  you’ll  use  parameters  to  SetWindowExt  with  the  desired  logical  size  of  the 
logical  window,  and  parameters  to  SetViewportExt  with  the  actual  height  and  width  of  the 
client  area.  When  Windows  adjusts  these  extents,  it  has  to  fit  the  logical  window  within  the 
physical  viewport,  which  can  result  in  a  section  of  the  client  area  falling  outside  the  logical 
window.  You  should  call  SetWindowExt  before  you  call  SetViewportExt  to  make  the  most 
efficient  use  of  space  in  the  client  area. 

For  instance,  suppose  you  want  a  “traditional”  one-quadrant  virtual  coordinate  sys¬ 
tem  where  (0,  0)  is  at  the  lower  left  corner  of  the  client  area  and  the  width  ranges  from  0  to 
32,767  and  the  height  from  0  to  32,767.  You  want  the  x  and  y  units  to  have  the  same  physical 
dimensions.  Here’s  what  you  need  to  do: 

SetMapMode  (hdc.  MM_I SOTROP I C )  ; 

SetWindowExt  (hdc,  32767,  32767)  ; 

SetViewportExt  (hdc,  cxClient,  -cyClient)  ; 

SetViewportOrg  (hdc,  0,  cyClient)  ; 

If  you  then  obtain  the  window  and  viewport  extents  using  GetWindowExt  and  GetView- 
portExt,  you’ll  find  that  they  are  not  the  values  you  specified.  Windows  adjusts  the  extents 
based  on  the  aspect  ratio  of  the  display  device  so  that  logical  units  on  the  two  axes  repre¬ 
sent  the  same  physical  dimensions. 
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If  the  client  area  is  wider  than  it  is  high  (in  physical  dimensions),  Windows  adjusts 
the  x  extents  so  that  the  logical  window  is  narrower  than  the  client-area  viewport.  The 
logical  window  will  be  positioned  at  the  left  of  the  client  area: 


You  can’t  display  anything  starting  on  the  right  side  of  the  client  area  beyond  the  range  of 
the  jc-axis,  because  that  requires  a  logical  jc- coordinate  greater  than  32,767. 

If  the  client  area  is  higher  than  it  is  wide  (in  physical  dimensions),  Windows  adjusts 
the  y  extents.  The  logical  window  will  be  positioned  at  the  bottom  of  the  client  area: 


Now  you  can’t  display  anything  at  the  top  of  the  client  area,  because  you  need  a  logical 
jy-coordinate  greater  than  32,767. 

If  you  prefer  that  the  logical  window  always  be  positioned  at  the  left  and  top  of  the 
client  area,  you  can  change  the  code  on  the  preceding  page  to  the  following: 

SetMapMode  (hdc,  MM_I SOTROP I C )  ; 

SetWindowExt  (hdc.  32767,  32767)  ; 

SetViewportExt  (hdc,  cxClient,  -cyClient)  ; 

SetWindowOrg  (hdc,  0,  32767)  ; 
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In  the  SetWindowOrg  call  we’re  saying  that  we  want  the  logical  point  (0,  32767)  to  be 
mapped  to  the  device  point  (0,  0).  Now  if  the  client  area  is  higher  than  it  is  wide,  the  coor¬ 
dinates  are  arranged  like  this: 


For  a  CLOCK-like  image,  you  might  want  to  use  a  four-quadrant  Cartesian  coordinate  sys¬ 
tem  with  arbitrarily  scaled  axes  in  four  directions  where  the  logical  point  (0,  0)  is  in  the 
center  of  the  client  area.  If  you  want  each  axis  to  range  from  0  to  1000  (for  instance),  you 
use  this  code: 

SetMapMode  (hdc,  MM_I SOTROP IC )  ; 

SetWindowExt  (hdc,  1000,  1000)  ; 

SetViewportExt  (hdc,  cxClient  /  2,  -cyClient  /  2)  ; 

SetViewportOrg  (hdc,  cxClient  /  2,  cyClient  /  2)  ; 

The  logical  coordinates  look  like  this  if  the  client  area  is  wider  than  it  is  high: 
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The  logical  coordinates  are  also  centered  if  the  client  area  is  higher  than  it  is  wide: 


i 

<  -x 

+y 

+x 

> 

-y 
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Keep  in  mind  that  no  clipping  is  implied  in  window  or  viewport  extents.  When  calling  GDI 
functions,  you  are  still  free  to  use  logical  x  and  jp  values  less  than  -1000  and  greater  than 
+1000.  Depending  on  the  shape  of  the  client  area,  these  points  may  or  may  not  be  visible. 

With  the  MM_ISOTROPIC  mapping  mode,  you  can  make  logical  units  larger  than 
pixels.  For  instance,  suppose  you  want  a  mapping  mode  with  the  point  (0,  0)  at  the  upper 
left  corner  of  the  display  and  values  of  y  increasing  as  you  move  down  (like  MM_TEXT) 
but  with  logical  coordinates  in  sixteenths  of  an  inch.  This  mapping  mode  would  let  you 
draw  a  ruler  starting  at  the  top  and  left  side  of  the  client  area  with  divisions  of  sixteenths 
of  an  inch: 

SetMapMode  (hdc,  MM_I SOTROP I C )  ; 

SetWindowExt  (hdc, 

(short)  ( 160L  *  GetDeviceCaps  (hdc,  HORZSIZE)  /  254), 

(short)  ( 160L  *  GetDeviceCaps  (hdc,  VERTSIZE)  /  254))  ; 

SetViewportExt  (hdc,  GetDeviceCaps  (hdc,  HORZRES), 

GetDeviceCaps  (hdc,  VERTRES ) )  ; 

In  this  code,  the  viewport  extents  are  set  to  the  pixel  dimensions  of  the  entire  screen.  The 
window  extents  must  be  set  to  the  dimensions  of  the  entire  screen  in  units  of  sixteenths  of 
an  inch.  The  HORZSIZE  and  VERTSIZE  indexes  to  GetDeviceCaps  return  the  dimensions 
of  the  device  in  millimeters.  If  we  were  working  with  floating-point  numbers,  we  would 
convert  the  millimeters  to  inches  by  dividing  by  25.4  and  then  convert  inches  to  sixteenths 
of  an  inch  by  multiplying  by  16.  However,  because  we’re  working  with  integers,  we  must 
multiply  by  160  and  divide  by  254.  The  calculation  is  done  in  long  integers  to  prevent 
overflow. 
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For  most  output  devices,  this  code  makes  the  logical  unit  much  larger  than  the  physi¬ 
cal  unit.  Everything  you  draw  on  the  device  will  have  coordinate  values  that  map  to  an 
increment  of  Vi6  inch.  You  cannot  draw  two  horizontal  lines  that  are  V32  inch  apart,  how¬ 
ever,  because  that  would  require  a  fractional  logical  coordinate. 

MM-ANISOTROPIC:  Stretching  the  image  to  fit 

When  you  set  the  viewport  and  window  extents  in  the  MM -ISOTROPIC  mapping  mode, 
Windows  adjusts  the  values  so  that  logical  units  on  the  two  axes  have  the  same  physical 
dimensions.  In  the  MM -ANISOTROPIC  mapping  mode,  Windows  makes  no  adjustments 
to  the  values  you  set.  This  means  that  MM -ANISOTROPIC  does  not  necessarily  maintain 
the  correct  aspect  ratio. 

One  way  you  can  use  MM -ANISOTROPIC  is  to  have  arbitrary  coordinates  for  the 
client  area,  as  we  did  with  MM-ISOTROPIC.  This  code  sets  the  point  (0,  0)  at  the  lower  left 
corner  of  the  client  area  with  both  the  x-  and  y-axes  ranging  from  0  to  32,767: 

SetMapMode  (hdc.  MM_AN I SOTROP I C )  ; 

SetWindowExt  (hdc.  32767,  32767)  ; 

SetViewportExt  (hdc,  cxClient,  -cyClient)  ; 

SetViewportOrg  (hdc,  0,  cyClient)  ; 

With  MM_ISOTROPIC,  similar  code  caused  part  of  the  client  area  to  be  beyond  the  range 
of  the  axes.  With  MM_ANISOTROPIC,  the  upper  right  corner  of  the  client  area  is  always 
the  point  (32767,  32767)  regardless  of  its  dimensions.  If  the  client  area  is  not  square,  then 
logical  x  and  y  units  will  be  different  physical  dimensions. 

In  the  previous  section  on  the  MM -ISOTROPIC  mapping  mode,  I  discussed  drawing 
a  CLOCK-like  image  in  the  client  area  where  both  the  x-  and  jp-axes  ranged  from  -1000  to 
1000.  You  can  do  something  similar  with  MM_ANISOTROPIC: 

SetMapMode  (hdc.  MM_AN I SOTROP I C )  ; 

SetWindowExt  (hdc,  1000,  1000)  ; 

SetViewportExt  (hdc,  cxClient  /  2,  -cyClient  /  2)  ; 

SetViewportOrg  (hdc,  cxClient  /  2,  cyClient  /  2)  ; 

The  difference  with  MM_ANISOTROPIC  is  that  in  general  the  clock  would  be  drawn  as  an 
ellipse  rather  than  a  circle. 

Another  way  to  use  MM_ANISOTROPIC  is  to  set  x  and  y  units  to  fixed  but  unequal 
values.  For  instance,  if  you  have  a  program  that  displays  only  text,  you  may  want  to  set 
coarse  coordinates  based  on  the  height  and  width  of  a  single  character: 

SetMapMode  (hdc,  MM_AN I SOTROP I C )  ; 

SetWindowExt  (hdc.  1,  1)  ; 

SetViewportExt  (hdc,  cxChar,  cyChar)  ; 

(This  assumes  that  cxChar  and  cyChar  are  the  width  and  height  of  a  character  in  pixels,  for 
a  fixed-pitch  font.)  Now  you  can  specify  character  row  and  column  coordinates  in  the 
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TextOut  call  rather  than  pixel  coordinates.  For  instance,  the  following  statement  displays 
the  text  Hello  three  character  spaces  from  the  left  and  two  character  rows  from  the  top: 

TextOut  (hdc,  3.  2.  "Hello”.  5)  ; 

This  is  almost  like  working  in  text  mode  in  the  non-Windows  MS-DOS  environment! 

When  you  first  set  the  MM -ANISOTROPIC  mapping  mode,  it  always  inherits  the  ex¬ 
tents  of  the  previously  set  mapping  mode,  which  can  be  very  convenient.  One  way  of 
thinking  about  MM-ANISOTROPIC  is  that  it  “unlocks”  the  extents;  that  is,  it  allows  you  to 
change  the  extents  of  an  otherwise  fully  constrained  mapping  mode.  For  instance,  sup¬ 
pose  you  want  to  use  the  MM_LOENGLISH  mapping  mode  because  you  want  logical  units 
to  be  0.01  inch.  But  you  don’t  want  the  values  along  the  jp-axis  to  increase  as  you  move  up 
the  screen — you  prefer  the  MM_TEXT  orientation,  where  y  values  increase  moving  down. 
Here’s  the  code: 

DWORD  dwExtent  ; 

[other program  lines] 

SetMapMode  (hdc,  MM.LOENGLISH)  ; 

SetMapMode  (hdc.  MM_AN I SOTRO P I C )  ; 

dwExtent  =  GetVi ewportExt  (hdc)  ; 

SetViewportExt  (hdc.  LOWORD  (dwExtent),  -HIWORD  (dwExtent))  ; 

We  first  set  the  mapping  mode  to  MM-LOENGLISH.  Then  we  liberate  the  extents  by  set¬ 
ting  the  mapping  mode  to  MM -ANISOTROPIC.  The  GetViewportExt  obtains  the  viewport 
extents  encoded  in  a  DWORD  variable.  Then  we  call  SetViewportExt  with  the  extents  ex¬ 
tracted  from  the  DWORD  using  the  LOWORD  and  HIWORD  macros,  except  that  we  make 
the  y  extent  negative. 

The  WHATSIZE  Program 

We’ll  use  various  mapping  modes  as  we  explore  the  GDI  functions  in  the  next  four  chap¬ 
ters.  Right  now,  let’s  simply  look  at  the  size  of  a  client  area  in  terms  of  inches  and  milli¬ 
meters.  The  WHATSIZE  program,  shown  in  Figure  11-5,  displays  the  size  of  the  client  area 
in  terms  of  units  associated  with  the  six  fully  constrained  mapping  modes:  MM-TEXT, 
MM-LOMETRIC,  MM-HIMETRIC,  MM-LOENGLISH,  MM-HIENGLISH,  and  MM-TWIPS. 
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WHATSIZE.MAK 

# . . . 

#  WHATSIZE.MAK  make  file 
#~ . - 

whatsize.exe  :  whatsize.obj  whatsize.def 

$(WINLINK)  whatsize,  whatsize,  NUL,  $(WINLIB) .  whatsize 
rc  -t  whatsize.exe 

whatsize.obj  :  whatsize. c 
$ ( W I NCC )  whatsize. c 


WHATSIZE.C 

/* . - . 

WHATSIZE.C  -  What  Size  is  the  Window? 

(c)  Charles  Petzold,  1992 
. - . */ 


#include  <windows.h> 
#include  <stdio.h> 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT.  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "WhatSize"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndcl ass .cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbrBackg round 
wndclass. IpszMenuName 
wndclass. IpszClassNane 


CS_H REDRAW  !  CS.VREDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  IDI.APPLICATION)  ; 
LoadCursor  (NULL,  IDC.ARROW)  ; 
GetStockObject  (WHITE.BRUSH)  ; 

NULL  ; 
szAppName  ; 


Figure  1 1  -5.  The  WHATSIZE  program. 


(continued) 


535 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "What  Size  is  the  Window?", 
WS_OVERLAPPEDWINDOW, 

CW_USEDEFAULT,  CWJJSEDEFAULT, 

CW.USEDEFAULT,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  Show  (HWND  hwnd,  HDC  hdc,  short  xText,  short  yText,  short  nMapMode, 
char  *szMapMode) 

{ 

char  szBuffer  [60]  ; 

RECT  rect  ; 

SaveDC  (hdc)  ; 

SetMapMode  (hdc,  nMapMode)  ; 

GetClientRect  (hwnd,  &rect)  ; 

DPtoLP  (hdc,  ( LPPOINT)  &rect,  2)  ; 


RestoreDC  (hdc,  -1)  ; 


TextOut  (hdc,  xText,  yText,  szBuffer, 

sprintf  (szBuffer,  "%-20s  %7d  %7d  %7d  %7d",  szMapMode, 
rect. left,  rect. right,  rect. top,  rect. bottom) )  ; 


} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  char  szHeading  []  = 

"Mapping  Mode  Left  Right  Top  Bottom"  ; 

static  char  szUndLine  []  = 


static  short  cxChar,  cyChar  ; 
HDC  hdc  ; 


(continued) 
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PAINTSTRUCT  ps  ; 
TEXTMETRIC  tm  ; 


switch  (message) 

{ 

case  WM_CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc.  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

GetTextMetrics  (hdc,  &tm)  ; 

cxChar  =  tm.tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm.tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 
return  0  ; 


case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 


SetMapMode  (hdc,  MM_ANIS0TR0PIC)  ; 
SetWindowExt  (hdc,  1,  1)  ; 
SetViewportExt  (hdc,  cxChar,  cyChar)  ; 


TextOut  (hdc,  1.  1,  szHeading,  sizeof  szHeading  -  1)  ; 
TextOut  (hdc,  1,  2,  szUndLine,  sizeof  szUndLine  -  1)  ; 


Show  (hwnd,  hdc,  1,  3, 
Show  (hwnd,  hdc,  1,  4, 
Show  (hwnd.  hdc,  1,  5, 
Show  (hwnd,  hdc,  1,  6, 
Show  (hwnd,  hdc,  1,  7, 
Show  (hwnd,  hdc,  1,  8, 


MM_TEXT, 
MM_LOMETRIC, 
MM_H I METRI C , 
MM.LOENGLISH, 
MM_H IENGLISH, 
MM_TW IPS, 


"TEXT  (pixels)")  ; 
"LOMETRIC  (.1  mm)")  ; 
"HIMETRIC  (.01  mm)")  ; 
"LOENGLISH  (.01  in.)") 
"HIENGLISH  (.001  in.)") 
"TWIPS  (1/1440  in.)")  ; 


EndPaint  (hwnd,  &ps)  ; 
return  0  ; 


case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
} 
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WHATSIZE.DEF 


WHATSIZE.DEF  module  definition  file 


NAME 


WHATSIZE 


DESCRIPTION  ’What  Size  is  the  Window?  (c)  Charles  Petzold,  1992* 
EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE* 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


For  ease  in  displaying  the  information  using  the  TextOut  function,  WHATSIZE  uses  the 
MM -ANISOTROPIC  mapping  mode  with  logical  units  set  to  character  dimensions: 

SetMapMode  (hdc,  MM_AN I SOTROP I C )  ; 

SetWindowExt  (hdc,  1,  1)  ; 

SetViewportExt  (hdc,  cxChar,  cyChar)  ; 

The  program  can  then  specify  logical  coordinates  to  TextOut  in  character  row  and  charac¬ 
ter  column  coordinates  for  a  fixed-pitch  font. 

When  WHATSIZE  needs  to  obtain  the  size  of  the  client  area  for  one  of  the  six  map¬ 
ping  modes,  it  saves  the  current  device  context,  sets  a  new  mapping  mode,  obtains  the 
client-area  coordinates,  converts  them  to  logical  coordinates,  and  then  restores  the  original 
mapping  mode  before  displaying  the  information.  This  code  is  in  WHATSIZE’s  Show 
function: 

SaveDC  (hdc)  ; 

SetMapMode  (hdc,  nMapMode)  ; 

GetClientRect  (hwnd,  &rect)  ; 

DPtoLP  (hdc,  ( LPPOINT)  &rect,  2)  ; 

RestoreDC  (hdc,  -1)  ; 

Figure  11-6  shows  a  typical  display  from  WHATSIZE. 
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Drawing 

Graphics 


Some  theoretical  discussions  of  computer  graphics  assume  that  you  are  supplied  with  only 
two  graphics  primitives — a  “write  pixel”  routine  and  a  “read  pixel”  routine.  In  theory,  you 
can  do  anything  you  want  with  these  two  functions.  Drawing  a  line,  for  instance,  simply 
requires  that  you  call  the  “write  pixel”  routine  numerous  times,  adjusting  the  x-  and  y- 
coordinates  appropriately. 

In  reality,  you  can  indeed  do  anything  you  want  with  only  “write  pixel”  and  “read 
pixel”  routines — if  you  don’t  mind  waiting  for  the  results.  It  is  much  more  efficient  for  a 
graphics  system  to  do  line  drawing  and  other  complex  graphics  operations  at  the  level  of 
the  device  driver,  which  can  have  its  own  optimized  code  to  perform  the  operations. 
Moreover,  as  video  display  technology  becomes  more  sophisticated,  the  adapter  boards 
will  contain  graphics  coprocessors  that  allow  the  video  hardware  itself  to  draw  the  figures. 

But  of  course,  no  graphics  language  would  be  complete  without  routines  to  draw  one 
pixel  at  a  time,  and  that’s  where  we’ll  begin.  From  there  we’ll  proceed  to  drawing  lines,  and 
then  we’ll  tackle  bounded  areas. 


DRAWING  POINTS 

You  can  draw  a  pixel  of  a  particular  color  with  the  GDI  SetPixel  function: 
rgbActualColor  =  SetPixel  (hdc,  x,  y,  rgbColor)  ; 
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The  rgbColor parameter  is  an  unsigned  long  integer  (32  bits)  where  the  lowest  3  bytes  rep¬ 
resent  the  intensity  of  red,  green,  and  blue.  You  can  construct  this  color  value  using  the 
RGB  macro: 

rgbColor  =  RGB  ( by Red ,  byGreen,  byBlue)  ; 

(Chapters  3  and  6  contain  a  more  extensive  discussion  of  Windows’  use  of  color.) 

Although  x  and  y  are  logical  coordinates,  SetPixel  colors  only  a  single  physical  pixel 
regardless  of  the  mapping  mode.  Because  SetPixel  draws  only  a  single  pixel,  the  use  of 
a  dithered  color  (a  color  that  combines  pixels  of  various  pure  colors)  is  meaningless.  For 
this  reason,  Windows  translates  the  rgbColor  parameter  to  a  pure  nondithered  color  and 
returns  that  color. 

SetPixel  is  almost  never  used  in  Windows  programs,  but  that  didn’t  prevent  us  from 
using  it  in  the  CONNECT  program  in  Chapter  4.  You  can  obtain  the  color  of  a  particular 
pixel  this  way: 

rgbColor  =  Get Pi xel  (hdc,  x,  y)  ; 


DRAWING  LINES 

After  drawing  points,  the  next  step  up  is  drawing  lines.  Windows  can  draw  straight  lines 
and  elliptical  lines.  An  elliptical  line  is  a  curved  line  on  the  circumference  of  an  ellipse. 
The  four  functions  that  draw  lines  are  LineTo  (straight  lines),  PolyLine( series  of  connected 
lines),  PolyPolyLine  ( multiple  series  of  connected  lines),  and  A rc  (elliptical  lines).  Five  at¬ 
tributes  of  the  device  context  affect  the  appearance  of  lines  that  you  draw  using  these 
functions:  current  pen  position  (for  LineTo  only),  pen,  background  mode  (for  nonsolid 
pens),  background  color  (for  the  OPAQUE  background  mode),  and  drawing  mode. 

The  LineTo  function  is  one  of  the  few  GDI  functions  that  does  not  include  the  full 
dimensions  of  the  object  to  be  drawn.  Instead,  LineTo  draws  a  line  from  the  current  pen 
position  defined  in  the  device  context  up  to  (but  not  including)  the  logical  point  specified 
in  the  LineTo  function.  In  the  default  device  context,  the  current  pen  position  is  initially  set 
at  the  logical  point  (0,  0).  If  you  call  LineTo  without  first  setting  the  current  pen  position 
(or  the  viewport  or  window  origin),  it  draws  a  line  starting  at  the  upper  left  corner  of  the 
client  area. 

To  draw  a  line  from  the  logical  point  ( xStart ,  yStart)  to  the  logical  point  ( xEnd , 
yEnd),  you  first  must  use  MoveTo  to  set  the  current  pen  position  to  the  point  ( xStart ,  yStart ): 

MoveTo  (hdc,  xStart,  yStart)  ; 

MoveTo  doesn’t  draw  anything.  It  simply  changes  the  current  pen  position.  You  can  then 
use  LineTo  to  draw  the  line: 

LineTo  (hdc,  xEnd,  yEnd)  ; 


542 


Chapter  12:  Drawing  Graphics 


This  draws  the  line  up  to  (but  not  including)  the  point  (. xEnd ,  yEnd ).  Following  the  LineTo 
call,  the  current  pen  position  is  set  to  (, xEnd ,  yEnd). 

Normally,  LineTo  is  the  only  Windows  function  that  uses  the  current  pen  position, 
and  MoveTo  and  LineTo  are  the  only  functions  that  change  it.  (An  option  set  by  SetText- 
Align  lets  TextOut  also  use  the  current  position.)  You  can  obtain  the  current  pen  position 
by  calling: 

dwPoint  =  GetCurrentPosition  (hdc)  ; 

The  dwPoint  return  value  is  an  unsigned  long  (or  doubleword)  that  contains  the  jc- 
coordinate  in  the  low  word  and  the  ^-coordinate  in  the  high  word.  You  can  use  the 
LOWORD  and  HIWORD  macros  to  extract  the  two  coordinates,  or  you  can  convert  the 
value  of  dwPoint  to  a  POINT  structure  using  the  MAKEPOINT  macro: 

point  =  MAKEPOINT  (dwPoint)  ; 

The  following  code  draws  a  grid  in  the  client  area  of  a  window,  spacing  the  lines  1 
inch  apart  starting  from  the  upper  left  corner.  The  variable  hwnd  is  assumed  to  be  a  handle 
to  the  window,  hdc  is  a  handle  to  the  device  context,  red  is  a  structure  of  type  RECT,  and  x 
and  y  are  short  integers: 

SetMapMode  (hdc.  MM.LOENGLISH)  ; 

GetCl ientRect  (hwnd,  &rect)  ; 

DPtoLP  (hdc.  ( LPPOINT)  &rect,  2)  ; 

for  (x  =  0  ;  x  <  rect. right  ;  x  +=  100) 

{ 

MoveTo  (hdc,  x,  0)  ; 

LineTo  (hdc,  x,  rect . bottom)  ; 

} 

for  (y  =  0  ;  y  >  rect. bottom  ;  y  -=  100) 

{ 

MoveTo  (hdc,  0,  y)  ; 

LineTo  (hdc.  rect. right,  y)  ; 

} 

The  client-area  dimensions  are  saved  in  the  RECT  structure  called  rect  and  converted  to 
logical  points  with  DPtoLP.  After  the  DPtoLP  conversion,  rect. right  is  the  width  of  the 
client  area  in  units  of  0.01  inch,  and  rect. bottom  is  the  negative  height  of  the  client  area. 
Note  that  y  is  decremented  (not  incremented)  in  the  second  for  loop  because  the  MM_LO- 
ENGLISH  mapping  mode  uses  decreasing  values  of  y  as  you  move  down  the  display. 

Although  it  may  seem  like  a  nuisance  to  be  forced  to  use  two  functions  to  draw  a 
single  line,  the  current  pen  position  attribute  comes  in  handy  when  you  want  to  draw 
a  series  of  connected  lines.  For  instance,  you  might  want  to  define  an  array  of  5  points 
(10  values)  that  draw  the  outline  of  a  rectangle: 

POINT  pt  [5]  =  {  100,  100,  200,  100,  200,  200, 

100,  200,  100,  100  }  ; 
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Notice  that  the  last  point  is  the  same  as  the  first.  Now  you  need  only  use  MoveTo  for  the  first 
point  and  LineTo  for  the  successive  points: 

MoveTo  (hdc,  pt[0].x,  pt[0].y)  ; 

for  (i  =  1  ;  i  <  5  ;  i++) 

LineTo  (hdc,  pt[i].x,  pt[i].y)  ; 

Because  LineTo  draws  from  the  current  point  up  to  (but  not  including)  the  point  in  the 
LineTo  function,  no  coordinate  gets  written  twice  by  this  code.  While  overwriting  points  is 
not  a  problem  with  a  display,  it  might  not  look  good  on  a  plotter  or  with  some  drawing 
modes  (to  be  covered  shortly). 

When  you  have  an  array  of  points  that  you  want  connected  with  lines,  you  can  draw 
the  lines  more  easily  using  the  PolyLine  function.  This  statement  draws  the  same  rectangle 
as  in  the  code  shown  above: 

PolyLine  (hdc,  &pt,  5)  ; 

The  last  parameter  is  the  number  of  points.  We  could  also  have  represented  this  value  by 
(sizeof(pt)/sizeof( POINT)).  PolyLine  has  the  same  effect  as  an  initial  MoveTo  function  fol¬ 
lowed  by  multiple  LineTo  functions.  However,  PolyLine  doesn’t  use  or  change  the  current 
pen  position. 

The  Arc  function  is  a  little  more  complex.  Here’s  the  general  syntax: 

Arc  (hdc,  xLeft,  yTop,  xRight,  yBottom, 
xStart,  yStart,  xEnd,  yEnd)  ; 

The  Arc  function  draws  a  line  on  the  circumference  of  an  ellipse  that  is  bounded  by  a  rect¬ 
angle  with  the  upper  left  corner  at  ( xLeft ,  yTop )  and  the  lower  right  corner  at  ( xRight , 
yBottom ).  The  arc  starts  at  the  intersection  of  the  ellipse  and  the  line  connecting  ( xStart , 
yStart)  with  the  center  of  the  ellipse.  The  arc  is  drawn  counterclockwise  around  the  cir¬ 
cumference  of  the  ellipse  and  ends  at  the  intersection  of  the  ellipse  and  the  line  connect¬ 
ing  point  ( xEnd ,  yEnd )  with  the  center  of  the  ellipse.  If  you’re  having  trouble  visualizing 
this,  don’t  worry  about  it:  I’ll  discuss  the  Arc  function  in  much  more  detail  after  we’ve 
covered  rectangles  and  ellipses. 

Using  Stock  Pens 

When  you  call  LineTo ,  PolyLine ,  PolyPolyLine ,  or  Arc,  Windows  uses  the  “pen”  currently 
selected  in  the  device  context  to  draw  the  line.  The  pen  determines  the  line’s  color,  its 
width,  and  its  style,  which  can  be  solid,  dotted,  or  dashed.  The  pen  in  the  default  device 
context  is  called  BLACK_PEN.  This  pen  draws  a  solid  black  line  with  a  width  of  one  pixel 
regardless  of  the  mapping  mode.  BLACK_PEN  is  one  of  three  “stock  pens”  that  Windows 
provides.  The  other  two  are  WHITE _PEN  and  NULL_PEN.  NULL_PEN  is  a  pen  that 
doesn’t  draw.  You  can  also  create  your  own  customized  pens. 
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In  your  Windows  programs,  you  refer  to  pens  with  a  handle.  WINDOWS.H  includes  a 
type  definition  named  HPEN,  a  handle  to  a  pen.  You  can  define  a  variable  (for  instance, 
hPeri)  using  this  type  definition: 

HPEN  hPen  ; 

You  obtain  the  handle  to  one  of  the  stock  pens  by  a  call  to  GetStockObject.  For  instance, 
suppose  you  want  to  use  the  stock  pen  called  WHITE_PEN.  You  get  the  pen  handle 
like  this: 

hPen  =  GetStockObject  (WHITE_PEN)  ; 

Now  you  must  make  that  pen  the  currently  selected  pen  in  the  device  context,  which 
requires  a  call  to  SelectObject : 

SelectObject  (hdc,  hPen)  ; 

After  this  call,  the  lines  you  draw  using  LineTo,  Polyline,  or  Arc  will  use  WHITE_PEN  un¬ 
til  you  select  another  pen  into  the  device  context  or  release  the  device  context. 

Rather  than  explicitly  defining  an  hPen  variable,  you  can  instead  combine  the 
GetStockObject  and  SelectObject  calls  in  one  statement: 

SelectObject  (hdc.  GetStockObject  (WHITE_PEN) )  ; 

If  you  then  want  to  return  to  using  BLACK_PEN,  you  can  get  the  handle  to  that  stock  object 
and  select  it  into  the  device  context  in  one  statement: 

SelectObject  (hdc,  GetStockObject  ( B LAC K_P EN ) )  ; 

SelectObject  returns  the  handle  to  the  pen  that  had  been  previously  selected  into  the 
device  context.  If  you  start  off  with  a  fresh  device  context  and  call: 

hPen  =  SelectObject  (hdc,  GetStockObject  ( WH I TE_P EN ) )  ; 

then  the  current  pen  in  the  device  context  will  be  WHITE_PEN,  and  the  variable  hPen  will 
be  the  handle  to  BLACK_PEN.  You  can  then  select  BLACK_PEN  into  the  device  context 
by  calling: 

SelectObject  (hdc,  hPen)  ; 

Creating,  Selecting,  and  Deleting  Pens 

Although  the  pens  defined  as  stock  objects  are  certainly  convenient,  you  are  limited  to 
only  a  solid  black  pen,  a  solid  white  pen,  or  no  pen  at  all.  If  you  want  to  get  fancier  than 
that,  you  must  create  your  own  pens.  Here’s  the  general  procedure:  You  create  a  “logical 
pen,”  which  is  merely  the  description  of  a  pen,  using  the  function  CreatePen  or  CreatePen- 
Indirect.  These  functions  return  a  handle  to  the  logical  pen.  You  select  the  pen  into  the 
device  context  by  calling  SelectObject.  You  can  then  draw  lines  with  this  new  pen.  Only 


545 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


one  pen  can  be  selected  into  the  device  context  at  any  one  time.  After  you  release  the  de¬ 
vice  context  (or  after  you  select  another  pen  into  the  device  context),  you  can  delete  the 
logical  pen  you’ve  created  by  calling  DeleteObject.  When  you  do  so,  the  handle  to  the  pen 
is  no  longer  valid. 

A  logical  pen  is  a  “GDI  object.”  You  create  and  use  the  pen,  but  the  pen  doesn’t 
belong  to  your  program.  The  pen  really  belongs  to  the  GDI  module.  A  pen  is  one  of  six  GDI 
objects  that  you  can  create.  The  other  five  are  brushes,  bitmaps,  regions,  fonts,  and 
palettes. 

This  brings  me  to  a  very  important  point:  Normally,  Windows  cleans  up  thoroughly 
when  a  program  terminates.  The  one  big  exception  is  for  GDI  objects.  When  a  program 
terminates,  Windows  doesn’t  automatically  delete  GDI  objects  that  the  program  has  cre¬ 
ated.  The  program  itself  is  responsible  for  deleting  GDI  objects. 

Three  rules  govern  the  use  of  GDI  objects  such  as  pens: 

■  Delete  all  GDI  objects  that  you  create. 

■  Don’t  delete  GDI  objects  while  they  are  selected  in  a  valid  device  context. 

■  Don’t  delete  stock  objects. 

These  are  not  unreasonable  rules,  but  they  can  be  a  little  tricky  sometimes.  We’ll  run 
through  some  examples  to  get  the  hang  of  how  the  rules  work. 

The  general  syntax  for  the  CreatePen  function  looks  like  this: 

hPen  =  CreatePen  (nPenStyle,  nWidth,  rgbColor)  ; 

The  nPenStyle  parameter  determines  whether  the  pen  draws  a  solid  line  or  a  line  made  up 
of  dots  or  dashes.  The  parameter  can  be  one  of  the  following  identifiers  defined  in  WIN- 
DOWS.H:  PS_SOLID,  PS_DASH,  PS_DOT,  PS_DASHDOT,  PS_DASHDOTDOT,  PS_NULL, 
and  PS-INSIDEFRAME.  Figure  12-1  shows  the  kind  of  line  that  each  style  produces. 

PSSOLID  - 

PS  _ DASH  - 

PS_DOT  - - 

PSDASHDOT  - 

PSDASHDOTDOT  - 

PSNULL 

PSJNSIDEFRAME  - 

Figure  1 2-1 .  The  seven  pen  styles. 

For  the  PS_SOLID,  PS_NULL,  and  PS_INSIDEFRAME  styles,  the  nWidth  parameter  is  the 
width  of  the  pen  in  logical  units.  For  instance,  if  the  mapping  mode  is  MM_LOENGLISFI, 
a  pen  with  an  nWidth  of  10  will  be  0.1  inch  wide.  When  you  draw  a  line  with  a  PS_SOLID 
or  PS_NULL  pen,  the  width  of  the  pen  will  extend  0.05  inch  on  either  side  of  the  line.  (The 
PS_INSIDEFRAME  style  is  a  little  different.)  For  the  MM -ANISOTROPIC  mapping  mode, 
Windows  uses  logical  units  on  the  x-axis  to  determine  the  physical  width  of  the  pen.  An 
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riWidth  value  of  0  directs  Windows  to  use  one  physical  unit  (1  pixel)  for  the  pen  width.  The 
stock  pens  are  1  pixel  wide.  If  you  specify  a  dotted  or  dashed  pen  style  with  a  physical 
width  greater  than  1,  Windows  will  use  a  solid  pen  instead. 

The  rgbColor  parameter  to  CreatePen  is  an  unsigned  long  integer  specifying  the 
color  of  the  pen.  For  all  the  pen  styles  except  PS-INSIDEFRAME,  when  you  select  the  pen 
into  the  device  context,  Windows  converts  this  parameter  to  the  nearest  pure  color  that 
the  device  can  represent.  The  PS_INSIDEFRAME  style  is  the  only  pen  style  that  can  use  a 
dithered  color,  and  then  only  when  the  width  is  greater  than  1.  (The  PS_INSIDEFRAME 
style  has  another  peculiarity,  which  I’ll  discuss  later  in  this  chapter  in  the  section  on  the 
“bounding  box.”) 

You  can  also  create  a  pen  by  setting  up  a  structure  of  type  LOGPEN  (“logical  pen”) 
and  calling  CreatePenlndirect.  If  your  program  uses  a  lot  of  different  pens  that  you  can  ini¬ 
tialize  in  your  source  code,  this  method  is  more  efficient.  First  you  define  a  structure  vari¬ 
able  of  type  LOGPEN — for  instance,  logpen : 

LOGPEN  logpen  ; 

This  structure  has  three  members:  lopnStyle( WORD)  is  the  pen  style,  lopnWidth  (POINT) 
is  the  pen  width  in  logical  units,  and  lopnColor (DWORD)  is  the  pen  color.  The  lopnWidth 
member  is  a  structure  of  type  POINT,  but  Windows  uses  only  the  lopnWidth. x  value  for  the 
pen  width  and  ignores  lopnWidth.y.  Then  you  create  the  pen  by  passing  the  address  of 
the  structure  to  CreatePenlndirect : 

hPen  =  CreatePenlndirect  (&logpen)  ; 

You  can  also  obtain  the  logical  pen  information  for  an  existing  pen.  If  you  already 
have  a  handle  to  a  pen,  you  can  copy  the  data  that  defines  the  logical  pen  into  a  structure  of 
type  LOGPEN  by  using  the  GetOhject  call: 

GetObject  (hPen,  sizeof  (LOGPEN),  (LPSTR)  &logpen)  ; 

Note  that  the  CreatePen  and  CreatePenlndirect  functions  do  not  require  a  handle 
to  a  device  context.  These  functions  create  logical  pens  that  have  no  connection  with  a 
device  context  until  you  call  SelectObject.  For  instance,  you  can  use  the  same  logical  pen 
for  several  different  devices,  such  as  the  screen  and  a  printer.  Logical  pens  with  a  non¬ 
zero  nWidth  have  a  logical  width;  they  have  a  physical  width  only  when  you  select  the 
pen  into  a  device  context,  and  then  the  physical  width  depends  on  the  device  context’s 
mapping  mode. 

Here’s  one  method  for  creating,  selecting,  and  deleting  pens.  Suppose  your  program 
uses  three  pens — a  black  pen  of  width  1,  a  red  pen  of  width  3,  and  a  black  dotted  pen.  You 
can  first  define  variables  for  storing  the  handles  to  these  pens: 

static  HPEN  hPenl,  hPen2,  hPen3  ; 
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During  processing  of  WM-CREATE,  you  can  create  the  three  pens: 

hPenl  =  CreatePen  (PS-SOLID,  1,  0L)  ; 

hPen2  =  CreatePen  (PS_S0LID,  3,  RGB  (255,  0,  0))  ; 

hPen3  =  CreatePen  (PS_D0T,  0.  0L)  ; 

During  processing  of  WM -PAINT  (or  any  other  time  you  have  a  valid  handle  to  a  device 

context),  you  can  select  one  of  these  pens  into  the  device  context  and  draw  with  it: 

SelectObject  (hdc,  hPen2)  ; 

[LineTo,  PolyLine,  or  Arc  calls] 

SelectObject  (hdc,  hPenl)  ; 

[other  LineTo,  PolyLine,  or  Arc  calls] 

During  processing  of  WM -DESTROY,  you  can  delete  the  three  pens  you  created: 

DeleteObject  (hPenl)  ; 

DeleteObject  (hPen2)  ; 

DeleteObject  (hPen3)  ; 

This  is  the  most  straightforward  method  for  creating,  selecting,  and  deleting  pens,  but  it  re¬ 
quires  that  the  logical  pens  take  up  memory  space  during  the  entire  time  your  program  is 
running.  You  might  instead  want  to  create  the  pens  during  each  WM -PAINT  message  and 
delete  them  after  you  call  EndPaint.  (You  can  delete  them  before  calling  EndPaint ,  but  you 
have  to  be  careful  not  to  delete  the  pen  currently  selected  in  the  device  context.) 

You  might  also  want  to  create  pens  on  the  fly  and  combine  the  CreatePen  and  the 
SelectObject  calls  in  the  same  statement: 

SelectObject  (hdc,  CreatePen  (PS_DASH,  0,  RGB  (255,  0,  0)))  ; 

Now  when  you  draw  lines,  you’ll  be  using  a  red  dashed  pen.  When  you’re  finished  draw¬ 
ing  the  red  dashed  lines,  you  can  delete  the  pen.  Whoops!  How  can  you  delete  this  pen 
when  you  haven’t  saved  the  pen  handle?  Recall  that  SelectObject  returns  the  handle  to  the 
pen  previously  selected  in  the  device  context.  So  you  can  delete  the  pen  by  selecting 
the  stock  BLACK_PEN  into  the  device  context  and  deleting  the  value  returned  from 
SelectObject : 

DeleteObject  (SelectObject  (hdc,  GetStockObject  (BLACK_PEN) ) )  ; 

Here’s  another  method.  When  you  select  a  newly  created  pen  into  the  device  con¬ 
text,  save  the  handle  to  the  pen  that  SelectObject  returns: 

hPen  =  SelectObject  (hdc,  CreatePen  (PS.DASH,  0,  RGB  (255,  0,  0)))  ; 

What  is  hPenl  If  this  is  the  first  SelectObject  call  you’ve  made  since  obtaining  the  device 
context,  hPen  is  a  handle  to  the  BLACK_PEN  stock  object.  You  can  now  select  that  pen  into 
the  device  context  and  delete  the  pen  you  created  (the  handle  returned  from  this  second 
SelectObject  c all)  in  one  statement: 
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DeleteObject  (SelectObject  (hdc,  hPen))  ; 

If  you  delete  a  GDI  object  while  it  is  selected  in  a  device  context  and  then  try  to  draw 
lines,  Windows  will  respond  with  a  fatal  error  because  the  device  context  doesn’t  contain  a 
valid  pen.  This  is  a  fairly  obvious  bug  to  track  down.  Failing  to  delete  GDI  objects  that  you 
create  can  be  a  more  difficult  bug  to  discover,  because  the  program  will  appear  to  work 
fine.  If  your  program  creates  the  same  logical  pen  for  every  WM_PAINT  message,  you 
might  want  to  cause  the  client  area  to  be  repainted  over  and  over  and  check  to  see  if  free 
memory  starts  to  drop.  The  FREEMEM  program  shown  in  Chapter  5  can  identify  problems 
related  to  dropping  memory.  If  HEAPWALK  shows  a  lot  of  small  GDI  segments  after  your 
program  has  terminated,  some  of  them  may  be  GDI  objects  you  have  failed  to  delete 
properly. 

Avoiding  Device  Dependencies 

Pen  widths  will  vary  according  to  the  resolution  of  the  display.  The  stock  pens  (and  any 
pen  created  with  a  width  of  0)  are  1  pixel  wide,  which  on  a  high-resolution  display  can 
result  in  very  thin  lines. 

If  you’re  working  in  MM_TEXT,  you  might  want  to  obtain  the  width  of  the  single- 
line  window  border  by  calling  GetSystemMetrics  with  the  SM_CXBORDER  and  SM_- 
CYBORDER  indexes.  These  values  are  appropriate  for  pen  widths.  You  can  also  use  one 
of  the  metric  mapping  modes  and  set  specific  physical  widths  for  the  pens  your  program 
needs  to  create. 

Pen  colors  are  also  susceptible  to  device  dependencies.  If  you  develop  a  program  on 
a  color  display  and  then  run  the  program  on  a  monochrome  display,  you  can  be  in  for  some 
unpleasant  surprises.  Except  for  the  PS_INSIDEFRAME  style,  Windows  always  uses  pure 
colors  for  pens,  and  on  a  monochrome  system,  pens  are  either  black  or  white.  For  instance, 
on  your  color  EGA,  you  might  be  fond  of  magenta  pens  on  a  white  background: 

hPen  =  CreatePen  (PS_S0LID,  1,  RGB  (255,  0,  255))  ; 

But  on  a  monochrome  system,  the  pure  color  that  is  closest  to  magenta  is  white,  so  the  pen 
will  be  invisible.  If  you  want  to  use  colored  pens,  be  sure  the  sum  of  the  red,  green,  and 
blue  values  is  less  than  or  equal  to  381  (half  the  maximum  sum  of  the  three  primary  colors) 
for  any  pen  that  should  default  to  black  and  greater  than  381  for  any  pen  that  should  de¬ 
fault  to  white. 

Filling  In  the  Gaps 

The  use  of  dotted  pens  and  dashed  pens  raises  an  interesting  question:  What  happens  to 
the  gaps  between  the  dots  and  the  dashes?  The  coloring  of  the  gaps  depends  on  both  the 
background  mode  and  the  background  color  attributes  defined  in  the  device  context.  The 
default  background  mode  is  OPAQUE,  which  means  that  Windows  fills  in  the  gaps  with  the 
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background  color,  which  by  default  is  white.  This  is  consistent  with  the  WHITE_BRUSH 
that  many  programs  use  in  the  window  class  for  erasing  the  background  of  the  window. 

You  can  change  the  background  color  that  Windows  uses  to  fill  in  the  gaps  by  calling: 

SetBkColor  (hdc,  rgbColor)  ; 

As  with  the  rgbColor  value  used  for  the  pen  color,  Windows  converts  this  background 
color  to  a  pure  color.  You  can  obtain  the  current  background  color  defined  in  the  device 
context  by  calling  GetBkColor. 

You  can  also  prevent  Windows  from  filling  in  the  gaps  by  changing  the  background 
mode  to  TRANSPARENT: 

SetBkMode  (hdc,  TRANSPARENT)  ; 

Windows  will  ignore  the  background  color  and  will  not  fill  in  the  gaps.  You  can  obtain  the 
current  background  mode  (either  TRANSPARENT  or  OPAQUE)  by  calling  GetBkMode. 

Drawing  Modes 

The  appearance  of  lines  drawn  on  the  display  is  also  affected  by  the  drawing  mode  de¬ 
fined  in  the  device  context.  Imagine  drawing  a  line  that  has  a  color  based  not  only  on  the 
color  of  the  pen  but  also  on  the  original  color  of  the  display  area  where  the  line  is  drawn. 
Imagine  a  way  in  which  you  could  use  the  same  pen  to  draw  a  black  line  on  a  white  surface 
and  a  white  line  on  a  black  surface  without  knowing  what  color  the  surface  is.  Could  such  a 
facility  be  useful  to  you?  It’s  made  possible  by  the  drawing  mode. 

When  Windows  uses  a  pen  to  draw  a  line,  it  actually  performs  a  bitwise  Boolean 
operation  between  the  pixels  of  the  pen  and  the  pixels  of  the  destination  display  surface. 
Performing  a  bitwise  Boolean  operation  with  pixels  is  called  a  “raster  operation,”  or 
“ROP.”  Because  drawing  a  line  involves  only  two  pixel  patterns  (the  pen  and  the  destina¬ 
tion),  the  Boolean  operation  is  called  a  “binary  raster  operation,”  or  “ROP2.”  Windows 
defines  16  ROP2  codes  that  indicate  how  Windows  combines  the  pen  pixels  and  the  desti¬ 
nation  pixels.  In  the  default  device  context,  the  drawing  mode  is  defined  as  R2_COPYPEN, 
meaning  that  Windows  simply  copies  the  pixels  of  the  pen  to  the  destination,  which  is  how 
we  normally  think  about  pens.  There  are  15  other  ROP2  codes. 

Where  do  these  16  different  ROP2  codes  come  from?  For  illustration  purposes,  let’s 
assume  a  monochrome  system.  The  destination  color  (the  color  of  the  window’s  client 
area)  can  be  either  black  (which  we’ll  represent  by  a  0)  or  white  (1).  The  pen  also  can  be 
either  black  or  white.  There  are  four  combinations  of  using  a  black  or  white  pen  to  draw  on 
a  black  or  white  destination:  a  white  pen  on  a  white  destination,  a  white  pen  on  a  black 
destination,  a  black  pen  on  a  white  destination,  and  a  black  pen  on  a  black  destination. 

What  happens  to  the  destination  after  you  draw  with  the  pen?  One  possibility  is  that 
the  line  is  always  drawn  as  black  regardless  of  the  pen  or  destination  color:  This  drawing 
mode  is  indicated  by  the  ROP2  code  R2 -BLACK.  Another  possibility  is  that  the  line  is 
drawn  as  black  except  when  both  the  pen  and  destination  are  black,  in  which  case  the  line 
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is  drawn  as  white.  Although  this  might  be  a  little  strange,  Windows  has  a  name  for  it:  The 
drawing  mode  is  called  R2_NOTMERGEPEN.  Windows  performs  a  bitwise  OR  operation 
on  the  destination  pixels  and  the  pen  pixels  and  then  inverts  that  result. 

The  table  below  shows  all  16  ROP2  drawing  modes.  The  table  indicates  how  the  origi¬ 
nal  pen  (P)  and  destination  (D)  colors  are  combined  for  the  resultant  destination  color. 

The  column  labeled  “Boolean  Operation”  uses  C  notation  to  show  how  the  destina¬ 
tion  pixels  and  pen  pixels  are  combined. 


Pen  (P): 
Destination  (D): 

1 

1 

1 

0 

0 

1 

0 

0 

Boolean 

Operation 

Drawing  Mode 

Results: 

0 

0 

0 

0 

0 

R2 -BLACK 

0 

0 

0 

1 

~(P  !  D) 

R2  -NOTMERGEPEN 

0 

0 

1 

0 

~P  &  D 

R2  _M  ASKNOTPEN 

0 

0 

1 

1 

~P 

R2-NOTCOPYPEN 

0 

1 

0 

0 

P&-D 

R2  _M  ASKPENNOT 

0 

1 

0 

1 

-D 

R2_NOT 

0 

1 

1 

0 

PAD 

R2-XORPEN 

0 

1 

1 

1 

~(P  &  D) 

R2  _NOTM  ASKPEN 

1 

0 

0 

0 

P&D 

R2-MASKPEN 

1 

0 

0 

1 

~(P  A  D) 

R2  -NOTXORPEN 

1 

0 

1 

0 

D 

R2-NOP 

1 

0 

1 

1 

i 

*T3 

a 

R2  -MERGENOTPEN 

1 

1 

0 

0 

p 

R2-COPYPEN  (default) 

1 

1 

0 

1 

P  1  ~D 

R2  -MERGEPENNOT 

1 

1 

1 

0 

P  !  D 

R2-MERGEPEN 

1 

1 

1 

1 

1 

R2-WHITE 

You  can  set  a  new  drawing  mode  in  the  device  context  by: 

Set R0P2  (hdc,  nDrawMode)  ; 

The  nDrawMode  parameter  is  one  of  the  values  listed  in  the  “Drawing  Mode”  column  of 
the  table.  You  can  obtain  the  current  drawing  mode  using  the  function: 

nDrawMode  =  GetR0P2  (hdc)  ; 

The  device  context  default  is  R2_COPYPEN,  which  simply  transfers  the  pen  color  to 
the  destination.  The  R2_NOTCOPYPEN  mode  draws  white  if  the  pen  color  is  black  and 
black  if  the  pen  color  is  white.  The  R2_BLACK  mode  always  draws  black,  regardless  of  the 
color  of  the  pen  or  the  background.  Likewise,  the  R2 -WHITE  mode  always  draws  white. 
The  R2_NOP  mode  is  a  “no  operation”:  It  leaves  the  destination  unchanged. 
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We  started  out  using  an  example  of  a  pure  monochrome  system.  In  reality,  on  a 
monochrome  display  Windows  can  simulate  various  shades  of  gray  by  dithering  black  and 
white  pixels.  When  drawing  a  pen  on  a  dithered  background,  Windows  simply  performs 
the  bitwise  operation  on  a  pixel-by-pixel  basis.  The  R2_NOT  mode  always  inverts  the  des¬ 
tination,  again  regardless  of  the  color  of  the  pen.  This  mode  is  useful  when  you  don’t  know 
the  color  of  the  background,  because  it  guarantees  that  the  pen  will  be  visible.  (Well, 
almost  guarantees — if  the  background  is  a  50  percent  gray,  then  the  pen  will  be  virtually 
invisible.) 

The  ROP2LOOK  Program 

The  ROP2LOOK  program,  shown  in  Figure  12-2,  lets  you  experiment  with  these  16  ROP2 
codes. 


ROP2LOOK.MAK 

,# . ----- 

#  R0P2L00K.MAK  make  file 
#- 

rop21ook.exe  :  rop21ook.obj  rop21ook.def  rop21ook.res 

$(WINLINK)  rop21 ook,  rop21ook,  NUL,  $(WINLIB),  rop21ook 
rc  -t  rop21ook.res 

rop21ook.obj  :  rop21ook.c 
$ ( WI NCC )  rop21ook.c 

rop21ook.res  :  rop21ook.rc 
HWINRC)  rop21  ook. rc 


ROP2LOOK.C 


/* . . 

R0P2L00K.C  --  R0P2  Demonstration  Program 
(c)  Charles  Petzold,  1992 
- . - . . . . . */ 


#include  <windows.h> 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

Figure  12-2.  The  ROP2LOOK program.  (continued) 
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{ 

static  char  szAppName[]  =  "Rop2Look"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS_HREDRAW  !  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

wndclass. cbWndExtra  =  0  ; 

wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  NULL  ; 

wndclass. hCursor  =  LoadCursor  (NULL.  IDC_ARR0W)  ; 

wndclass. hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
wndclass. IpszMenuName  =  szAppName  ; 
wndclass. IpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "R0P2  Demonstration  Program", 
WS_OVERLAPPEDWI NDOW , 

CW_USEDEFAULT,  CW.USEDEFAULT, 

CWJJSEDEFAULT,  CW_USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  LOGPEN  lpBlack  =  {  PS.SOLID,  1,  1,  RGB  (  0,  0,  0)  }, 

lpWhite  =  {  PS.SOLID,  1,  1,  RGB  (255,  255,  255)  }  ; 
static  short  nDrawingMode  =  R2.C0PYPEN  ; 

HDC  hdc  ; 

HMENU  hMenu  ; 

HPEN  hPenBlack,  hPenWhite  ; 

PAINTSTRUCT  ps  ; 


(continued) 
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RECT  rect  ; 

short  i  ; 

switch  (message) 

{ 

case  WM_COMMAND  : 

hMenu  =  GetMenu  (hwnd)  ; 

CheckMenuItem  (hMenu,  nDrawingMode,  MF_UNCHECKED) 
nDrawingMode  =  wParam  ; 

CheckMenuItem  (hMenu,  nDrawingMode,  MF_CHECKED)  ; 
InvalidateRect  (hwnd,  NULL,  FALSE)  ; 
return  0  ; 

case  WM.PAINT  : 

hdc  =  BeginPaint  (hwnd.  &ps)  ; 

hPenBlack  =  CreatePenlndi rect  (&lpBlack)  ; 
hPenWhite  =  CreatePenlndi rect  ( &1 pWhi te )  ; 

SetMapMode  (hdc,  MM_ANI SOTROPIC )  ; 

GetClientRect  (hwnd,  &rect)  ; 

SetViewportExt  (hdc,  rect. right,  rect. bottom)  ; 
SetWindowExt  (hdc,  10,  4)  ; 

for  (i  =  0  ;  i  <  10  ;  i  +=  2) 

{ 

SetRect  (&rect,  i,  0,  i  +  2,  4)  ; 

Fill Rect  (hdc,  &rect,  GetStockObject  (i  /  2)) 
} 

SetR0P2  (hdc,  nDrawingMode)  ; 

SelectObject  (hdc,  hPenWhite)  ; 

MoveTo  (hdc,  1,  1)  ; 

LineTo  (hdc,  9,  1)  ; 

SelectObject  (hdc,  hPenBlack)  ; 

MoveTo  (hdc,  1.  3)  ; 

LineTo  (hdc,  9,  3)  ; 

EndPaint  (hwnd,  &ps)  ; 

DeleteObject  (hPenBlack)  ; 

DeleteObject  (hPenWhite)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 
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ROP2LOOK.RC 

/* . - . 

R0P2L00K.RC  resource  script 
.  .  . */ 

Rop2Look  MENU 

{ 

POPUP  "&Drawing  Mode" 

{ 

MENUITEM  "0\tR2_BLACK" ,  1 

MENUITEM  "l\tR2_N0TMERGEPEN”,  2 
MENUITEM  "2\tR2_MASKN0TPEN" ,  3 

MENUITEM  ”3\tR2_N0TC0PYPEN" ,  4 

MENUITEM  "4\tR2_MASKPENN0T" ,  5 

MENUITEM  ,,5\tR2_N0T" ,  6 

MENUITEM  ”6\tR2_X0RPEN" ,  7 

MENUITEM  "7\tR2_N0TMASKPEN" ,  8 

MENUITEM  ”8\tR2_MASKPEN",  9 
MENUITEM  ,,9\tR2_N0TX0RPEN”.  10 

MENUITEM  "A\tR2_N0P" ,  11 

MENUITEM  "B\tR2_MERGEN0TPEN",  12 
MENUITEM  "C\tR2_C0PYPEN" ,  13,  CHECKED 

MENUITEM  "D\tR2_MERGEPENN0T",  14 
MENUITEM  "E\tR2_MERGEPEN”,  15 
MENUITEM  '* F\ t R2_WH ITE” ,  16 

} 

} 


ROP2LOOK.DEF 


R0P2L00K.DEF  module  definition  file 


NAME  R0P2L00K 

DESCRIPTION  ' R0P2  Demonstration  Program  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 
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The  program  draws  a  background  divided  into  five  sections  colored  with  the  white, 
light  gray,  gray,  dark  gray,  and  black  stock  brushes  (a  subject  that  well  get  to  soon).  It  then 
draws  with  two  very  thick  pens:  a  white  pen  on  the  top  and  a  black  pen  on  the  bottom.  You 
can  select  one  of  the  16  ROP2  codes  from  the  menu.  Figure  12-3  shows  the  white  pen  on  the 
top  and  the  black  pen  on  the  bottom  with  the  drawing  mode  set  to  R2_NOTMERGEPEN: 
The  white  pen  always  displays  as  black,  and  the  black  pen  inverts  the  destination. 

ROP2LOOK  uses  initialized  logical  pen  structures  for  the  white  and  black  pens. 
You’ll  note  that  both  these  pens  have  a  logical  width  of  1.  Why  do  they  appear  so  thick?  The 
program  uses  the  MM_ANISOTROPIC  mapping  mode  and  sets  the  width  of  the  client  area 
to  10  logical  units  and  the  height  to  4  logical  units.  The  pens  are  therefore  one-tenth  the 
width  of  the  client  area. 


Figure  1 2-3.  The  ROP2LOOK  display  with  the  drawing  mode  set  to  R2-NOTMERGEPEN. 

ROP2  and  Color 

The  drawing  mode  gets  more  interesting — and  much  more  complex — when  color  is  in¬ 
troduced.  Let’s  assume  a  display  capable  of  eight  pure  colors  (such  as  the  EGA  and  VGA  in 
versions  of  Windows  prior  to  version  3).  The  pen  can  be  any  of  these  eight  pure  colors,  and 
for  simplicity’s  sake,  let’s  restrict  the  background  to  these  colors  also.  The  eight  colors  are 
combinations  of  the  bits  in  the  red,  green,  and  blue  color  planes,  as  shown  in  the  following 
table — a  1  means  the  color  is  illuminated,  and  a  0  means  the  color  is  off. 
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Red 

Green 

Blue 

Pure  Color 

Red 

Green 

Blue 

Pure  Color 

0 

0 

0 

Black 

1 

0 

0 

Red 

0 

0 

1 

Blue 

1 

0 

1 

Magenta 

0 

1 

0 

Green 

1 

1 

0 

Yellow 

0 

1 

1 

Cyan 

1 

1 

1 

White 

Each  of  the  three  color  planes  is  affected  separately  by  the  raster  operation.  For  ex¬ 
ample,  say  you  have  a  cyan  background  color  and  a  magenta  pen  color,  and  your  drawing 
mode  is  R2_NOTMERGEPEN.  What  color  will  the  pen  actually  draw?  For  red,  the  pen  is  1 
(has  red),  and  the  destination  is  0  (no  red).  Looking  at  the  ROP2  table  on  page  551,  you  see 
that  the  result  is  0  (no  red).  For  green,  the  pen  is  0  (no  green),  and  the  destination  is  1  (has 
green),  so  the  result  is  0  (no  green).  For  blue,  the  pen  is  1  (has  blue),  and  the  destination  is  1 
(has  blue),  so  the  result  is  0  (no  blue).  Thus  the  line  has  no  red,  no  green,  and  no  blue.  The 
color  will  be  black. 

Let’s  take  the  R2_XORPEN  drawing  mode,  which  performs  a  bitwise  exclusive  OR 
operation  on  each  of  the  possible  combinations  in  the  three  color  planes.  The  following 
table  shows  the  resultant  color  for  all  combinations  of  the  eight  destination  colors  and  the 
eight  pen  colors. 


PEN  COLOR 


Destination 

Black 

Blue 

Green 

Cyan 

Red 

Magenta  Yellow 

White 

Black 

Black 

Blue 

Green 

Cyan 

Red 

Magenta 

Yellow 

White 

Blue 

Blue 

Black 

Cyan 

Green 

Magenta 

Red 

White 

Yellow 

Green 

Green 

Cyan 

Black 

Blue 

Yellow 

White 

Red 

Magenta 

Cyan 

Cyan 

Green 

Blue 

Black 

White 

Yellow 

Magenta 

Red 

Red 

Red 

Magenta 

Yellow 

White 

Black 

Blue 

Green 

Cyan 

Magenta 

Magenta 

Red 

White 

Yellow 

Blue 

Black 

Cyan 

Green 

Yellow 

Yellow 

White 

Red 

Magenta 

Green 

Cyan 

Black 

Blue 

White 

White 

Yellow 

Magenta 

Red 

Cyan 

Green 

Blue 

Black 

On  certain  devices  (particularly  on  256-color  video  boards),  the  bits  that  define  each  pixel 
may  not  correspond  to  color  in  a  consistent  manner,  and  the  results  of  using  some  drawing 
modes  are  not  well  defined. 

At  the  beginning  of  Chapter  11, 1  mentioned  that  Windows  GDI  is  strong  in  the  area  of 
raster  operations.  The  drawing  mode  is  one  example  of  that.  And  if  you  think  that  you’ll 
probably  never  ever  use  some  of  these  ROP2  codes,  just  wait  until  you  see  the  regular  raster 
operation  codes  in  Chapter  13 — there  are  more  than  200  raster  operations  that  you’ll 
probably  never  use.  But  it’s  nice  to  know  that  they’re  available. 
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DRAWING  FILLED  AREAS 

Now  let’s  take  the  next  step  up,  from  drawing  lines  to  drawing  figures.  Windows’  seven 
functions  for  drawing  filled  figures  with  borders  are  listed  in  the  table  below: 


Function 

Figure 

Rectangle 

Rectangle  with  square  corners 

Ellipse 

Ellipse 

RoundRect 

Rectangle  with  rounded  corners 

Chord 

Arc  on  the  circumference  of  an  ellipse  with  endpoints  connected 
by  a  chord 

Pie 

Pie  wedge  on  the  circumference  of  an  ellipse 

Polygon 

Multisided  figure 

PolyPolygon 

Multiple  multisided  figures 

Windows  draws  the  outline  of  the  figure  with  the  current  pen  selected  in  the  device 
context.  The  current  background  mode,  background  color,  and  drawing  mode  are  all  used 
for  this  outline,  just  as  if  Windows  were  drawing  a  line.  Everything  we  learned  about  lines 
also  applies  to  the  border  around  these  figures. 

The  figure  is  filled  with  the  current  brush  selected  in  the  device  context.  By  default, 
this  is  the  stock  object  called  WHITE_BRUSH,  which  means  that  the  interior  will  be  drawn 
as  white.  Windows  defines  six  stock  brushes:  WHITE_BRUSH,  LTGRAY_BRUSH,  GRAY- 
_BRUSH,  DKGR AY_ BRU SH ,  BLACK_BRUSH,  and  NULL-BRUSH  (or  HOLLOW- BRUSH). 
The  first  five  of  these  brushes  were  used  to  color  the  client  area  of  ROP2LOOK. 

You  can  select  one  of  the  stock  brushes  into  your  device  context  the  same  way  you 
select  a  stock  pen.  Windows  defines  HBRUSH  to  be  a  handle  to  a  brush,  so  you  can  first 
define  a  variable  for  the  brush  handle: 

HBRUSH  hBrush  ; 

You  can  get  the  handle  to  GRAY -BRUSH  by  calling  GetStockObject : 

hBrush  =  GetStockObject  (GRAY_BRUSH)  ; 

You  can  select  it  into  the  device  context  by  calling  SelectObject : 

SelectObject  (hdc,  hBrush)  ; 

Now  when  you  draw  one  of  these  figures,  the  interior  will  be  gray. 

If  you  want  to  draw  a  figure  without  a  border,  select  the  NULL-PEN  into  the  device 
context: 

SelectObject  (hdc,  GetStockObject  (NULL_PEN) )  ; 
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If  you  want  to  draw  the  outline  of  the  figure  without  filling  in  the  interior,  select  the 
NULL -BRUSH  into  the  device  context: 

SelectObject  (hdc,  GetStockObject  ( NU LL_BRUSH ) )  ; 

You  can  also  create  customized  brushes  just  as  you  can  create  customized  pens.  Well 
cover  that  topic  shortly. 

The  Bounding  Box 

The  Rectangle ,  Ellipse ,  RoundRect ,  Chord ,  and  Pie  functions  (as  well  as  the  Arc  line¬ 
drawing  function)  are  all  similar  in  that  they  are  built  up  from  a  rectangular  “bounding 
box.”  You  define  the  coordinates  of  a  box  that  encloses  the  object — a  bounding  box — and 
Windows  draws  the  object  within  this  box. 

The  simplest  filled  object  is  the  rectangle: 

Rectangle  (hdc.  xLeft,  yTop,  xRight,  yBottom)  ; 

The  point  {xLeft,  yTop )  is  the  upper  left  corner  of  the  rectangle,  and  ( xRight ,  yBottom)  is  the 
lower  right  corner;  both  points  are  expressed  in  logical  units.  A  figure  drawn  using  the 
Rectangle  function  is  shown  in  Figure  12-4.  In  the  MM_TEXT  mapping  mode,  xRight  must 
be  greater  than  xLeft,  and  yBottom  must  be  greater  than  yTop.  However,  in  all  the  other 
mapping  modes  (except  possibly  MM -ISOTROPIC  and  MM -ANISOTROPIC),  the  value  of 
yBottom  is  less  than  that  of  yTop  because  the  coordinates  on  the  jy-axis  increase  as  you 
move  up. 

Programmers  who  have  worked  with  graphics  before  are  accustomed  to  the  problem 
of  being  off  by  1  pixel.  Some  graphics  systems  draw  a  figure  to  encompass  the  right  and 
bottom  coordinates,  and  some  draw  figures  up  to  (but  not  including)  the  right  and  bottom 
coordinates.  Windows  uses  the  latter  approach,  but  there’s  an  easier  way  to  think  about  it. 

xLeft  xRight 

! - J —  yTop 


*  ■■■  • —  yBottom 

Figure  12-4.  A  figure  drawn  using  the  Rectangle  function. 
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Consider  the  function  call: 

Rectangle  (hdc,  1,  1,  5,  4)  ; 

I  mentioned  above  that  Windows  draws  the  figure  within  a  “bounding  box.”  You  can  think 
of  the  display  as  a  grid  where  each  pixel  is  within  a  grid  cell.  The  imaginary  bounding  box 
is  drawn  on  the  grid,  and  the  rectangle  is  then  drawn  within  this  bounding  box.  Here’s  how 
the  figure  would  be  drawn  in  the  MM_TEXT  mapping  mode: 

0  1  2  3  4  5  6 

0 
1 
2 

3 

4 

5 

The  area  separating  the  rectangle  from  the  top  and  left  of  the  client  area  is  1  pixel  wide. 
Windows  uses  the  current  brush  to  color  the  2  pixels  inside  the  rectangle. 

For  all  pen  styles  except  PS-INSIDEFRAME,  if  the  pen  used  to  draw  the  outline  is 
greater  than  1  pixel  wide,  then  the  pen  is  centered  on  the  border  so  that  part  of  the  line  may 
be  outside  the  bounding  box.  For  the  PS_INSIDEFRAME  pen  style,  the  entire  line  is  drawn 
inside  the  bounding  box. 

Once  you  know  how  to  draw  a  rectangle,  you  also  know  how  to  draw  an  ellipse,  be¬ 
cause  it  uses  the  same  parameters: 

Ellipse  (hdc,  xLeft,  yTop,  xRight,  yBottom)  ; 

A  figure  drawn  using  the  Ellipse  function  is  shown  (with  the  imaginary  bounding  box)  in 
Figure  12-5. 


xLeft  xRight 
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Windows  does  not  include  “square”  or  “circle”  functions.  In  all  mapping  modes  except 
MM -TEXT  and  MM -ANISOTROPIC,  you  can  easily  draw  squares  and  circles  using  the 
Rectangle  and  Ellipse  functions  by  making  the  difference  between  xLeft  and  xRight  the 
same  as  the  difference  between  yTop  and yBottom.  In  MM-TEXT,  squares  and  circles  are  a 
little  more  difficult.  You  have  to  call  GetDeviceCaps  with  the  ASPECTX  and  ASPECTY 
indexes  and  scale  the  dimensions  based  on  the  aspect  ratio  of  the  pixels.  In 
MM -ANISOTROPIC,  you  also  have  to  take  into  account  the  ratio  of  the  window  and 
viewport  extents. 

The  function  to  draw  rectangles  with  rounded  corners  uses  the  same  bounding  box 
as  the  Rectangle  and  Ellipse  functions  but  includes  two  more  parameters: 

RoundRect  (hdc,  xLeft.  yTop,  xRight,  yBottom, 

xCornerEll ipse,  yCorner El  1 i pse )  ; 

A  figure  drawn  using  this  function  is  shown  in  Figure  12-6. 

Windows  uses  a  small  ellipse  to  draw  the  rounded  corners.  The  width  of  this  ellipse 
is  xCornerEllipse,  and  the  height  is  yCornerEllipse ,  with  both  points  expressed  in  logical 
units.  Imagine  Windows  splitting  this  small  ellipse  into  four  quadrants  and  using  one 
quadrant  for  each  of  the  four  corners.  The  rounding  of  the  corners  is  more  pronounced  for 
larger  values  of  xCornerEllipse  and  yCornerEllipse.  If  xCornerEllipse  is  equal  to  the  differ¬ 
ence  between  xLeft  and  xRight  and  yCornerEllipse  is  equal  to  the  difference  between  yTop 
and  yBottom,  then  the  RoundRect  function  will  draw  an  ellipse. 

The  rounded  rectangle  shown  in  Figure  12-6  was  drawn  using  corner  ellipse  dimen¬ 
sions  calculated  with  these  formulas: 

xCornerEllipse  =  (xRight  -  xLeft)  /  4  ; 

yCornerEllipse  =  (yBottom  -  yTop)  /  4  ; 

This  is  an  easy  approach,  but  the  results  admittedly  don’t  look  quite  right,  because  the 
rounding  of  the  corners  is  more  pronounced  along  the  larger  rectangle  dimension.  To 

xLeft  xRight 

yTop  — 


yBottom  — 

xCornerEllipse 

Figure  12-6.  A  figure  drawn  using  the  RoundRect  function. 


yCornerEllipse 
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correct  this  problem,  you’ll  probably  want  to  make  xCornerE l lipse  equal  to  yCornerEllipse 
in  real  dimensions. 

The  Arc ,  Chord ,  and  Pie  functions  all  take  identical  parameters: 

Arc  (hdc,  xLeft,  yTop,  xRight,  yBottom, 
xStart,  yStart,  xEnd,  y End )  ; 

Chord  (hdc,  xLeft,  yTop,  xRight,  yBottom, 
xStart,  yStart,  xEnd,  y End )  ; 

Pie  (hdc,  xLeft,  yTop,  xRight,  yBottom, 
xStart,  yStart,  xEnd,  y End )  ; 

A  line  drawn  using  the  Arc  function  is  shown  in  Figure  12-7;  figures  drawn  using  the  Chord 
and  Pie  functions  are  shown  in  Figures  12-8  and  12-9. 


xStart 


Figure  12-7.  A  line  drawn  using  the  toe  function. 


xStart 


Figure  12-8.  A  figure  drawn  using  the  Chord  function. 
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xStart 


Figure  12-9.  A  figure  drawn  using  the  Fie  function. 

Windows  uses  an  imaginary  line  to  connect  (x Start,  yStart )  with  the  center  of  the  ellipse. 
At  the  point  at  which  that  line  intersects  the  bounding  box,  Windows  begins  drawing  an 
arc  in  a  counterclockwise  direction  around  the  circumference  of  the  ellipse.  Windows  also 
uses  an  imaginary  line  to  connect  ( xEnd ,  yEnd)  with  the  center  of  the  ellipse.  At  the  point 
at  which  that  line  intersects  the  bounding  box,  Windows  stops  drawing  the  arc. 

For  the  Arc  function,  Windows  is  now  finished,  because  the  arc  is  an  elliptical  line 
rather  than  a  filled  area.  For  the  Chord  function,  Windows  connects  the  endpoints  of  the 
arc.  For  the  Pze  function,  Windows  connects  each  endpoint  of  the  arc  with  the  center  of  the 
ellipse.  The  interiors  of  the  chord  and  pie-wedge  figures  are  filled  with  the  current  brush. 

The  ARCS  Program 

You  may  wonder  about  this  use  of  starting  and  ending  positions  in  the  Arc ,  Chord ,  and  Pie 
functions.  Why  not  simply  specify  starting  and  ending  points  on  the  circumference  of  the 
ellipse?  Well,  you  can,  but  you  would  have  to  figure  out  what  those  points  are.  Windows’ 
method  gets  the  job  done  without  requiring  such  precision. 

You  can  experiment  with  arcs,  chords,  and  pie  wedges  using  the  ARCS  program, 
shown  in  Figure  12-10  beginning  on  the  following  page.  The  program  draws  the  bounding 
box  and  the  ellipse  using  a  dotted  pen.  Your  menu  choice  determines  whether  the  pro¬ 
gram  draws  an  arc,  a  chord,  or  a  pie  wedge.  The  line  or  figure  is  drawn  with  a  pen  that  is  3 
pixels  wide.  The  starting  and  ending  points  are  connected  to  the  center  of  the  ellipse  with 
a  normal  black  pen. 
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ARCS.MAK 

# . 

//  ARCS.MAK  make  file 
# . - . - 

arcs.exe  :  arcs.obj  arcs.def  arcs. res 

KWINLINK)  arcs,  arcs,  NUL,  $(WINLIB),  arcs 
rc  -t  arcs. res 

arcs.obj  :  arcs.c  arcs.h 
$ ( WI NCC )  arcs.c 

arcs. res  :  arcs.rc  arcs.h 
$ ( W I N RC )  arcs.rc 


ARCS.C 


/*- . 

ARCS.C  --  Demonstrates  Drawing  Arcs,  Chords,  and  Pies 
(c)  Charles  Petzold,  1992 


*/ 


//include  <windows.h> 
//include  "arcs.h" 


long  FAR  PASCAL  ..export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Arcs"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass . 1 pfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass. hbrBackground 
wndclass. IpszMenuName 
wndclass . 1 pszCl ass Name 


=  CS.HREDRAW  !  CS.VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL,  IDC.ARR0W)  ; 
=  GetStockObject  (WHITE_BRUSH)  ; 
=  szAppName  ; 

=  szAppName  ; 


Figure  12-10.  The  ARCS  program. 


(continued) 
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RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Arcs,  Chords,  and  Pies", 
WSJDVERLAPPEDWINDOW, 

CWJJSEDEFAULT,  CWJJSEDEFAULT. 

CWJJSEDEFAULT,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  short  cxClient,  cyClient,  xl,  x2,  x3,  x4,  yl,  y2,  y3,  y4, 
nFigure  =  IDM.ARC  ; 

HDC  hdc  ; 

HMENU  hMenu  ; 

HPEN  hPen  ; 

PAINTSTRUCT  ps  ; 

switch  (message) 

{ 

case  WM.SIZE  : 

x3  =  y3  =  0  ; 

x4  =  cxClient  =  LOWORD  (IParam)  ; 
y4  =  cyClient  =  HIWORD  (IParam)  ; 
x2  =  3  *  (xl  =  cxClient  /  4)  ; 

y2  =  3  *  (yl  =  cyClient  /  4)  ; 

return  0  ; 

case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  I DM_ARC  : 
case  IDM.CHORD  : 
case  IDM.PIE  : 

hMenu  =  GetMenu  (hwnd)  ; 

CheckMenuItem  (hMenu,  nFigure,  MFJJNCHECKED)  ; 


(continued) 
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CheckMenuIten  (hMenu,  nFigure  =  wParam,  MF_CHECKED)  ; 
Inval idateRect  (hwnd,  NULL,  FALSE)  ; 
return  0  ; 

) 

break  ; 

case  WM_LBUTT0ND0WN  : 

if  (! (wParam  &  MK_SH I  FT ) ) 

{ 

x3  =  LOWORD  (IParam)  ; 
y3  =  H I WORD  (IParam)  ; 

Inval i dateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

} 

//  fall  through  for  MK_SHIFT 

case  WM_RBUTT0ND0WN  : 

x4  =  LOWORD  (IParam)  ; 
y4  =  HIWORD  (IParam)  ; 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

case  WM_PA I NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

hPen  =  SelectObject  (hdc,  CreatePen  (PS_D0T,  1,  0L))  ; 

Rectangle  (hdc,  xl.  yl,  x2,  y2)  ; 

Ellipse  (hdc,  xl,  yl,  x2,  y2)  ; 

DeleteObject  (SelectObject  (hdc,  CreatePen  (PS_S0LID,  3,  0L)))  ; 

switch  (nFigure) 

{ 

case  IDM_ARC  : 

Arc  (hdc,  xl,  yl,  x2,  y2,  x3,  y3,  x4,  y4)  ; 
break  ; 

case  IDM.CHORD  : 

Chord  (hdc,  xl,  yl,  x2,  y2,  x3,  y3,  x4,  y4)  ; 
break  ; 

case  IDM.PIE  : 

Pie  (hdc,  xl,  yl.  x2,  y2,  x3,  y3,  x4,  y4)  ; 
break  ; 

} 

DeleteObject  (SelectObject  (hdc.  hPen))  ; 


(continued) 
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MoveTo  (hdc,  x3,  y3)  ; 

LineTo  (hdc,  cxClient  /  2,  cyClient  /  2)  ; 
LineTo  (hdc,  x4,  y4)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WMJ3ESTR0Y  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
} 


ARCS.RC 


/* . 

ARCS.RC  resource  script 
. */ 


#include  "arcs.h" 

Arcs  MENU 
{ 

POPUP  ”&0pti ons" 

{ 

MENUITEM  M&ArcM,  IDM_ARC,  CHECKED 
MENUITEM  "&ChordM ,  IDM_CH0RD 
MENUITEM  M&Pie" ,  IDM_PIE 
} 


ARCS.H 

/* 

ARCS.H  header  file 

*/ 

#define  IDM_ARC  1 
#define  IDM.CHORD  2 
#define  IDM_PIE  3 
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ARCS.DEF 


ARCS.DEF  module  definition  file 


NAME  ARCS 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Arc,  Chord,  and  Pie  Drawing  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


When  you  click  on  the  client  area  using  the  left  mouse  button,  ARCS  uses  that  point  as  the 
starting  point,  which  is  the  point  (x3,  y3)  in  the  program.  Clicking  on  the  client  area  with 
the  right  mouse  button  sets  the  ending  point,  the  point  ( x4}  y4 ).  Users  with  a  one-button 
mouse  can  hold  down  the  Shift  key  and  click  the  mouse  to  set  the  ending  point. 

ARCS  also  shows  some  typical  pen-handle  manipulation.  After  the  program  gets  the 
device  context  by  calling  BeginPaint ,  it  creates  a  dotted  pen  and  selects  it  into  the  device 
context: 

hPen  =  SelectObject  (hdc,  CreatePen  (PS_D0T,  1,  0L))  ; 

The  hPen  handle  returned  from  SelectObject  is  a  handle  to  the  stock  BLACK_PEN. 

When  ARCS  needs  to  draw  the  arc,  chord,  or  pie  wedge,  it  creates  a  3-pixel-wide  pen 
and  selects  that  into  the  device  context: 

DeleteObject  (SelectObject  (hdc,  CreatePen  (PS_S0LID,  3,  0L)))  ; 

The  pen  handle  returned  from  SelectObject ,  which  is  the  handle  to  the  dotted  pen,  is  then 
deleted  using  DeleteObject. 

When  ARCS  needs  to  draw  the  lines  connecting  the  starting  and  ending  points  with 
the  center  of  the  ellipse,  it  selects  hPen — the  handle  to  the  stock  BLACK_PEN — into  the 
device  context  and  deletes  the  3-pixel-wide  pen  returned  from  SelectObject : 

DeleteObject  (SelectObject  (hdc,  hPen ) )  ; 

Now  the  two  pens  that  were  created  have  been  deleted.  The  pen  currently  selected  in  the 
device  context  is  a  stock  pen,  and  the  device  context  can  be  released. 
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The  Trigonometry  of  Pie  Charts 

If  you  use  the  Pie  function  to  create  pie  charts,  the  size  of  each  pie  wedge  will  be  based  on 
the  relative  sizes  of  data  items.  This  involves  calculating  starting  and  ending  points  of  the 
pie  figures  that  are  derived  from  the  internal  angle  of  the  pie  wedge. 

It’s  time  for  a  trigonometry  refresher.  In  a  Cartesian  coordinate  system  (with  x  in¬ 
creasing  to  the  right  and  y  increasing  as  it  moves  up),  we  can  draw  a  triangle  like  this: 


The  relationship  between  each  of  the  three  sides  of  the  triangle  and  the  angle  a  is  given  by 
the  formulas: 

sin  (a)  =  y/r 
cos  ( a )  =  x/r 
tan  (a)  =  y/x 

If  you  know  the  angle  a  (which  in  a  pie  chart  will  be  a  fraction  of  a  circle)  and  r  (which 
will  be  the  radius  of  the  circle),  you  can  determine  that  the  point  (x,  y)  is  equal  to: 

(r  *  cos  (a),  r  *  sin  (a)) 

In  the  C  library  functions  sin  and  cos ,  angles  are  specified  in  terms  of  radians.  There  are 
2  *  PI  radians  in  360  degrees. 

Let’s  try  drawing  a  pie  chart  that  uses  five  numbers.  For  convenience,  we’ll  set  this 
condition  with  a  ^define  statement: 

//define  NUM  5 

In  a  real  program,  that  would  be  a  variable. 

You’ll  also  find  it  convenient  to  define  an  identifier  called  TWO_PI  that  is  the  number 
of  radians  in  a  circle: 

//define  TWO.PI  (2.0  *  3.14159) 

Next  you  define  some  variables: 

static  short  nValues  [NUM]  =  {  3,  5,  2,  7,  4  }; 

short  i ,  nSum  [NUM  +  1]  ; 
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The  initialized  values  in  nValues  are  the  data  we’ll  be  graphing.  In  a  real  program,  these 
values  would  be  variables.  The  nSum  array  is  set  to  the  accumulated  sum  of  the  data  values 
where  the  first  element  of  the  array  is  set  to  0: 

nSum  [0]  =  0  ; 

for  (i  =  0  ;  i  <  NUM  ;  i++) 

nSum  [i  +  1]  =  nSum  [i]  +  nValues  [i]  ; 

The  array  element  nSum  [NUM]  is  the  sum  of  the  five  values. 

Now  we  are  ready  to  start  drawing  the  pie  chart.  Set  the  mapping  mode  to 
MM_ISOTROPIC,  which  is  the  mode  in  which  you  can  most  easily  draw  a  circle: 

SetMapMode  (hdc,  MM_I SOTROP I C )  ; 

SetWindowExt  (hdc.  400.  400)  ; 

SetViewportExt  (hdc,  xClient,  -yClient)  ; 

SetViewportOrg  (hdc,  xClient  /  2,  yClient  /  2)  ; 

The  logical  point  (0,  0)  is  the  center  of  the  client  area,  and  the  x-  and  jy- coordinates  define 
a  normal  Cartesian  coordinate  system. 

Our  pie  has  a  radius  of  100  logical  units.  Here’s  the  code  to  paint  the  five  pie 
segments: 

for  (i  =  0  ;  i  <  NUM  ;  i++) 

Pie  (hdc,  -100,  100,  100,  -100, 

(short)  (100.0  *  cos  (TWCLPI  *  nSum  [i]  /  nSum  [NUM])), 

(short)  (100.0  *  sin  (TWCLPI  *  nSum  [i]  /  nSum  [NUM])), 

(short)  (100.0  *  cos  (TWCLPI  *  nSum  [i  +  1]  /  nSum  [NUM])), 

(short)  (100.0  *  sin  (TWCLPI  *  nSum  [i  +  1]  /  nSum  [NUM])))  ; 

The  pie  chart  produced  from  this  code  is  shown  in  Figure  12-11.  The  first  pie  wedge  is  at  the 
right  of  the  pie  chart,  just  above  the  x-axis.  The  other  pie  wedges  are  drawn  in  a  counter¬ 
clockwise  direction. 


Figure  12-11,  A  pie  chart  drawn  using  the  Pie  function. 
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The  values: 

TWO_PI  *  nSum  [i]  /  nSum  [NUM] 

and: 

TWO_PI  *  nSum  [i  +  1]  /  nSum  [NUM] 

are  ratios  of  the  accumulated  sum  of  the  items  to  the  total  sum  of  the  items  converted  to 
angles  that  are  measured  counterclockwise  from  the  horizontal.  The  second  formula  in¬ 
cludes  the  item  that  the  particular  pie  wedge  represents;  the  first  does  not.  By  taking  the 
cosine  and  sine  of  these  angles  and  multiplying  by  100,  we’re  calculating  the  starting  and 
ending  points  on  the  circle. 

The  Polygon  Function  and  the  Polygon  Filling  Mode 

Polygon  is  the  sixth  function  for  drawing  a  bordered  and  filled  figure.  The  function  call  is 
similar  to  the  PolyLine  function: 

Polygon  (hdc,  IpPoints,  nCount)  ; 

The  IpPoints  parameter  is  a  far  pointer  to  an  array  of  POINT  structures  (in  logical  coordi¬ 
nates),  and  nCount  is  the  number  of  points.  If  the  last  point  in  this  array  is  different  from 
the  first  point,  Windows  adds  another  line  that  connects  the  last  point  with  the  first  point. 
(This  does  not  happen  with  the  PolyLine  function.) 

Windows  fills  this  bounded  area  with  the  current  brush  in  one  of  two  ways,  depend¬ 
ing  on  the  current  polygon  filling  mode  defined  in  the  device  context.  By  default,  the 
polygon  filling  mode  is  ALTERNATE,  which  means  that  Windows  fills  in  only  those  in¬ 
teriors  accessible  from  the  outside  of  the  polygon  by  crossing  an  odd  number  of  lines  (1,  3, 
5,  and  so  forth).  The  other  interiors  are  not  filled.  You  can  also  set  the  polygon  filling  mode 
to  WINDING,  in  which  case  Windows  generally  fills  in  all  the  interior  areas.  The  two 
polygon  filling  modes  are  most  simply  demonstrated  with  a  five-pointed  star.  In  Figure 
12-12  on  the  following  page,  the  star  on  the  left  was  drawn  with  the  ALTERNATE  mode,  and 
the  star  on  the  right  was  drawn  with  the  WINDING  mode.  Both  figures  were  drawn  with 
an  array  of  points  defined  like  this: 

static  POINT  pt  []  = 

{  -59.  -81.  0.  100.  59,  -81.  -95.  31.  95,  31  }  ; 

The  five  points  of  the  star  were  manually  calculated  from  trigonometric  tables.  The 
WM_PAINT  logic  looks  like  this: 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

hPen  =  CreatePen  (PS_S0LID,  3,  0L)  ; 

SelectObject  (hdc,  hPen)  ; 

SelectObject  (hdc,  GetStockObject  ( LTGRAY_BRUSH) )  ; 
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SetMapMode  (hdc.  MM.ISOTROPIC)  ; 

SetWindowExt  (hdc,  440,  -220)  ; 

SetViewportExt  (hdc,  xClient,  yClient)  ; 
SetWindowOrg  (hdc,  -110,  110)  ; 

SetPolyFil IMode  (hdc,  ALTERNATE)  ; 

Polygon  (hdc,  pt,  sizeof  (pt)  /  sizeof  (POINT))  ; 

SetWindowOrg  (hdc,  -330,  110)  ; 

SetPolyFil IMode  (hdc,  WINDING)  ; 

Polygon  (hdc,  pt,  sizeof  (pt)  /  sizeof  (POINT))  ; 

EndPaint  (hwnd,  &ps)  ; 

DeleteObject  (hPen)  ; 
break  ; 

The  PolyPolygon  function  draws  multiple  polygons. 


Figure  12-12.  Figures  drawn  with  the  two  polygon  filling  modes:  ALTERNATE  (left) 
and  WINDING  (right). 

Brushing  the  Interior 

The  interiors  of  the  Rectangle ,  RoundRect,  Ellipse ,  Chord ,  Pie,  Polygon ,  and  PolyPolygon 
figures  are  filled  in  with  the  current  brush  (also  sometimes  called  a  “pattern”)  selected  in 
the  device  context.  A  brush  is  an  8-by-8  bitmap  that  is  repeated  horizontally  and  vertically 
to  fill  the  area. 

When  Windows  uses  dithering  to  display  more  colors  than  are  normally  available  on 
a  display,  it  actually  uses  a  brush  for  the  color.  On  a  monochrome  system,  Windows  can  use 
dithering  of  black  and  white  pixels  to  create  64  different  shades  of  gray.  More  precisely, 
Windows  can  create  64  different  monochrome  brushes.  For  pure  black,  all  bits  in  the 
8-by-8  bitmap  are  0.  One  bit  out  of  the  64  is  made  1  (that  is,  white)  for  the  first  gray  shade, 
two  bits  are  white  for  the  second  gray  shade,  and  so  on,  until  all  bits  in  the  8-by-8  bitmap 
are  1  for  pure  white.  On  a  color  video  system,  dithered  colors  are  also  bitmaps,  and  a  much 
wider  range  of  color  is  available. 
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We’ve  already  used  stock  brushes.  Windows  also  has  four  functions  that  let  you 
create  logical  brushes.  You  select  the  brush  into  the  device  context  with  SelectObject.  Like 
logical  pens,  logical  brushes  are  GDI  objects.  Any  brush  that  you  create  must  be  deleted, 
but  it  must  not  be  deleted  while  it  is  selected  in  the  device  context. 

Here’s  the  first  function  to  create  a  logical  brush: 

hBrush  =  CreateSol idBrush  (rgbColor)  ; 

The  word  Solid  in  this  function  doesn’t  really  mean  that  the  brush  is  a  pure  color.  When 
you  select  the  brush  into  the  device  context,  Windows  creates  an  8-by-8  bitmap  for  a  dith¬ 
ered  color  and  uses  that  bitmap  for  the  brush.  We  used  CreateSolidBrush  in  the  COLORS1 
program  in  Chapter  6.  The  brush  was  used  as  the  background  color  defined  in  the  window 
class  structure. 

You  can  also  create  a  brush  with  “hatch  marks”  made  up  of  horizontal,  vertical,  or 
diagonal  lines.  Brushes  of  this  style  are  most  commonly  used  for  coloring  the  interiors  of 
bar  graphs  and  when  drawing  to  plotters.  The  function  for  creating  a  hatch  brush  is: 

hBrush  =  CreateHatchBrush  (nHatchStyle,  rgbColor)  ; 

The  nHatchStyle  parameter  describes  the  appearance  of  the  hatch  marks.  The  parameter 
can  be  one  of  the  following  styles:  HSJHORIZONTAL,  HS -VERTICAL,  HS _FDI AGONAL, 
HS.BDIAGONAL,  HS_CROSS,  and  HS_DIAGCROSS.  Figure  12-13  shows  the  kind  of  hatch 
marks  that  each  of  these  styles  produces. 
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Figure  12-13. 

The  six  hatch  brush  styles. 

The  rgbColor  parameter  of  CreateHatchBrush  is  the  color  of  the  hatch  lines.  When  you 
select  the  brush  into  a  device  context,  Windows  converts  this  color  to  the  nearest  pure 
color.  The  area  between  the  hatch  lines  is  colored  based  on  the  background  mode  and 
background  color  defined  in  the  device  context.  If  the  background  mode  is  OPAQUE, 
the  background  color  (which  is  also  converted  to  a  pure  color)  is  used  to  fill  in  the  spaces 
between  the  lines.  In  this  case,  neither  the  hatch  lines  nor  the  fill  color  can  be  a  dithered 
color.  If  the  background  mode  is  TRANSPARENT,  Windows  draws  the  hatch  lines  without 
filling  in  the  area  between  them. 

Earlier  I  discussed  the  problems  that  you  can  encounter  with  pen  colors  when  you 
develop  a  program  on  a  color  display  and  later  run  the  program  on  a  monochrome  display. 
You  should  beware  of  the  same  problems  when  you  choose  colors  for  hatch  marks  and  the 
brush  background.  Colored  hatch  marks  that  look  fine  on  a  color  display  may  disappear 
into  the  background  when  displayed  in  monochrome. 
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Because  brushes  are  always  8-by-8  bitmaps,  the  appearance  of  hatch  brushes  will 
also  vary  according  to  the  resolution  of  the  device  on  which  they  are  displayed.  Each  of  the 
hatch  marks  shown  in  Figure  12-13  was  drawn  in  a  32-by-l6-pixel  rectangle,  which  means 
that  the  8-by-8  bitmap  was  repeated  4  times  horizontally  and  2  times  vertically.  On  a  300- 
dots-per-inch  laser  printer,  the  same  32-by-l6-pixel  rectangle  would  occupy  an  area  about 
]/9  inch  wide  and  V19  inch  high. 

You  can  also  create  your  own  brushes  based  on  bitmaps  using  CreatePatternBrush : 

hBrush  =  CreatePatternBrush  (hBitmap)  ; 

This  function  was  discussed  in  Chapter  9.  The  hBitmap  parameter  is  a  handle  to  an  8-by-8 
bitmap.  How  you  get  this  bitmap  handle  is  covered  in  the  next  section  of  this  chapter. 

Windows  also  includes  a  function  that  encompasses  the  three  other  functions  for 
creating  brushes  ( CreateSolidBrush ,  CreateHatch Brush,  and  CreatePatternBrush ): 

hBrush  =  CreateBrushlndi rect  ( &1 ogbrush )  ; 


The  variable  logbrush  is  a  structure  of  type  LOGBRUSH  (“logical  brush”).  The  three  fields 
of  this  structure  are  shown  below.  The  value  of  the  IbStyle  field  determines  how  Windows 
interprets  the  other  two  fields: 


IbStyle  (WORD) 

IbColor  (DWORD) 

IbHatch  (short) 

BS-SOLID 

Color  of  brush 

Ignored 

BS -HOLLOW 

Ignored 

Ignored 

BS-HATCHED 

Color  of  hatches 

Hatch  brush  style 

BS-PATTERN 

Ignored 

Handle  to  bitmap 

Earlier  we  used  SelectObject  to  select  a  logical  pen  into  a  device  context,  DeleteObject 
to  delete  a  logical  pen,  and  GetObject  to  get  information  about  a  logical  pen.  You  can  use 
these  same  three  functions  with  brushes.  Once  you  have  a  handle  to  a  brush,  you  can  select 
the  brush  into  a  device  context  using  SelectObject : 

SelectObject  (hdc,  hBrush)  ; 

You  can  later  delete  a  created  brush  with  the  DeleteObject  function: 

DeleteObject  (hBrush)  ; 

Do  not  delete  a  brush  that  is  currently  selected  into  a  device  context,  however.  If  you  need 
to  obtain  information  about  a  brush,  you  can  call  GetObject : 

GetObject  (hBrush,  sizeof  (LOGBRUSH),  ( LPSTR)  &1 ogbrush)  ; 

where  logbrush  is  a  structure  of  type  LOGBRUSH. 
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Brushes  and  Bitmaps 

When  you  use  the  CreatePatternBrush  or  CreateBrushlndirect  function  with  the  IbStyle 
field  set  to  BS -PATTERN,  you  first  need  a  handle  to  a  bitmap.  The  bitmap  must  be  least  8 
pixels  wide  and  8  pixels  high.  If  it’s  larger,  Windows  uses  only  the  upper  left  corner  of  the 
bitmap  for  the  brush. 

Because  brushes  and  bitmaps  are  GDI  objects,  you  must  delete  any  that  you  create  in 
your  program  before  the  program  terminates.  When  you  create  a  brush  based  on  a  bitmap, 
Windows  makes  a  copy  of  the  bitmap  bits  for  use  when  drawing  with  the  brush.  You  can 
delete  the  bitmap  immediately  after  calling  CreatePatternBrush  (or  CreateBrushlndirect ) 
without  affecting  the  brush.  Similarly,  you  can  delete  the  brush  without  affecting  the 
bitmap. 

One  method  of  getting  a  handle  to  a  bitmap  was  discussed  in  Chapter  8.  You  can  use 
the  Image  Editor  to  create  a  bitmap  file  (with  the  extension  .BMP),  include  that  filename  in 
a  BITMAP  statement  in  the  resource  script,  and  then  load  the  bitmap  into  your  program. 
The  LoadBitmap  function  returns  a  handle  of  type  HBITMAP: 

hBitmap  =  LoadBitmap  (hlnstance,  IpszBitmap)  ; 

The  variable  IpszBitmap  is  the  name  of  the  bitmap  in  the  resource  script  file. 

The  second  method  of  getting  a  handle  to  a  bitmap  is  to  use  this  function: 

hBitmap  =  CreateBitmap  (nWidth,  nHeight,  nPlanes,  nBitsPixel,  IpBits)  ; 

To  create  a  bitmap  to  use  for  a  brush,  nWidth  and  nHeight  should  both  be  set  to  8.  If  you 
want  a  monochrome  bitmap,  nPlanes  and  nBitsPixel  should  both  be  set  to  1.  The  variable 
IpBits  is  a  long  pointer  to  an  array  of  bytes  containing  the  pixel  pattern  of  the  bitmap.  You 
can  set  this  parameter  to  NULL  if  you  want  to  create  an  uninitialized  bitmap,  in  which  case 
the  bitmap  will  contain  random  data. 

The  third  method  of  getting  a  handle  to  a  bitmap  is  this: 

hBitmap  =  CreateCompatibleBitmap  (hdc,  nWidth,  nHeight)  ; 

This  creates  a  bitmap  with  the  same  number  of  color  planes  and  the  same  number  of  color 
bits  per  pixel  as  the  device  context  indicated  by  hdc.  (The  only  reason  this  function  re¬ 
quires  hdc  is  to  get  this  color  information.)  The  bitmap  initially  contains  random  data. 

The  final  method  for  getting  a  handle  to  a  bitmap  requires  a  pointer  to  a  structure 
(here  named  bitmap)  of  type  BITMAP: 

hBitmap  =  CreateBi tmaplndi rect  Ubitmap)  ; 

Watch  out  for  the  difference  between  the  types  HBITMAP  and  BITMAP.  HBITMAP  is  a 
handle  to  a  bitmap.  BITMAP  is  a  structure  that  describes  the  bitmap.  The  BITMAP  struc¬ 
ture  has  seven  fields,  as  described  in  the  list  on  the  following  page.  Five  of  them  are  similar 
to  the  parameters  of  the  CreateBitmap  function. 
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bmType 

bmWidth 

bmHeight 

bmWidth  Bytes 

bmP lanes 

bmBitsPixel 

bmBits 


Set  to  0 

Width  of  bitmap  in  pixels 

Height  of  bitmap  in  pixels 

Number  of  bytes  in  each  raster  line 

Number  of  color  planes 

Number  of  adjacent  color  bits  per  pixel 

Far  pointer  to  an  array  of  bytes  containing  the  bitmap  pattern 


When  you  have  a  handle  to  a  bitmap,  you  can  use  GetObject  to  obtain  information 
about  the  bitmap: 


GetObject  (hBitmap,  sizeof  (BITMAP),  (LPSTR)  &bitmap)  ; 


where  bitmap  is  a  structure  of  type  BITMAP.  However,  GetObject  does  not  copy  a  valid  far 
pointer  into  the  bmBits  field.  To  get  the  actual  bits  that  make  up  the  bitmap,  you  can  call: 


GetBi tmapBi ts  (hBitmap,  dwCount,  IpBits)  ; 

GetBitmapBits  copies  dwCount  number  of  bytes  into  an  array  whose  address  is  IpBits.  You 
can  also  set  the  bits  of  a  bitmap  using  the  SetBitmapBits  function: 

SetBi tmapBi ts  (hBitmap,  dwCount,  IpBits)  ; 

The  bmBits  field  of  the  BITMAP  structure  and  the  IpBits  parameter  of  the  CreateBit- 
map ,  SetBitmapBits ,  and  GetBitmapBits  functions  are  far  pointers  to  an  array  of  bytes  that 
define  the  bitmap  pattern.  The  array  of  bytes  begins  with  the  top  scan  line.  Color  bitmaps 
may  be  organized  with  multiple  bits  per  pixel  or  multiple  color  planes  per  scan  line.  (I’ll 
discuss  this  more  in  the  next  chapter.)  If  you  wish  to  use  a  bitmap  as  a  brush  and  be  assured 
that  it  will  work  on  all  devices,  use  a  monochrome  bitmap. 

The  total  size  of  this  array  of  bytes  is  equal  to  (using  the  fields  of  the  logical  bitmap 
structure): 


bmPlanes  *  bmHeight  *  bmWidthBytes 

The  bmWidthBytes  field  is  the  width  of  each  scan  line  in  bytes.  This  value  must  be  the  even 
number  equal  to  or  the  next  even  number  greater  than: 

bmWidth  *  bmBitsPixel  /  8 

In  other  words,  each  scan  line  is  padded  with  bytes  if  necessary  to  get  an  integral  number 
of  words.  The  scan  line  is  padded  at  the  right  because  the  bytes  are  arranged  from  left  to 
right.  The  most  significant  bit  of  the  first  byte  is  the  leftmost  pixel. 
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Creating  and  Using  Bitmap  Brushes 


We’ve  covered  the  background  information  you  need  to  create  and  use  brushes  based  on 
bitmaps.  Now  let’s  put  that  information  to  work.  Let’s  say  that  you  want  to  draw  a  rectangle 
filled  in  with  a  brush  that  looks  like  little  bricks,  as  shown  in  Figure  12-14. 


Figure  12-14.  A  figure  filled  in  with  a  customized  brush. 
The  bitmap  you  need  has  a  pixel  pattern  that  looks  like  this: 


This  is  a  monochrome  bitmap  with  a  height  and  width  of  8.  Here  are  three  methods  you 
can  use  to  create  a  brush  based  on  this  bitmap. 

Method  one 

Create  an  8-by-8  monochrome  bitmap  in  SDKPAINT  that  resembles  the  diagram  shown 
above  and  save  it  under  the  name  BRICK.BMP.  In  your  resource  script  file,  include  a  state¬ 
ment  identifying  this  file  as  a  bitmap  and  naming  it  “Brick”: 

Brick  BITMAP  brick.bmp 


577 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


Within  your  program,  define  variables  of  type  HBITMAP  (handle  to  a  bitmap)  and 
HBRUSH  (handle  to  a  brush): 

HBITMAP  hBitmap  ; 

HBRUSH  hBrush  ; 

These  two  handles  are  set  by  the  following  statements: 

hBitmap  =  LoadBitmap  ( h Instance ,  "Brick")  ; 
hBrush  =  CreatePatternBrush  (hBitmap)  ; 

When  you  have  a  valid  device  context,  select  the  brush  into  the  device  context  and  display 
the  rectangle: 

SelectObject  (hdc,  hBrush)  ; 

Rectangle  (hdc.  xLeft,  yTop,  xRight,  yBottom)  ; 

When  you  release  the  device  context,  delete  the  brush  and  bitmap: 

DeleteObject  (hBrush)  ; 

DeleteObject  (hBitmap)  ; 

You  don’t  have  to  wait  until  you  release  the  device  context  to  delete  the 
do  so  anytime  after  you  create  the  brush  based  on  the  bitmap. 

Method  two 

This  method  defines  the  bitmap  pixels  within  the  program  as  an  array 
integers.  Each  integer  corresponds  to  a  scan  line  in  the  bitmap  pattern, 
white  and  a  0  bit  for  black: 

HBITMAP  hBitmap  ; 

HBRUSH  hBrush  ; 
static  WORD  wBrickBits  []  = 

{  0xFF,  0x0C ,  0x0C,  0x0C ,  0xFF,  0xC0,  0xC0.  0xC0  }  ; 

The  bitmap  is  created  using  CreateBitmap  by  referencing  this  array  of  integers: 

hBitmap  =  CreateBitmap  (8,  8,  1,  1.  ( LPSTR)  wBrickBits)  ; 
hBrush  =  CreatePatternBrush  (hBitmap)  ; 

SelectObject  (hdc,  hBrush)  ; 

Rectangle  (hdc,  xLeft,  yTop,  xRight,  yBottom)  ; 

After  you’re  finished  with  the  brush  and  the  bitmap  (and  the  brush  is  no  longer  selected  in 
a  valid  device  context),  you  delete  the  bitmap  and  the  brush: 

DeleteObject  (hBrush)  ; 

DeleteObject  (hBitmap)  ; 


bitmap — you  can 


of  eight  unsigned 
A  1  bit  is  used  for 
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Rather  than  using  an  array  of  integers  for  the  bitmap’s  bits,  you  can  instead  use  an 
array  of  unsigned  characters.  Because  each  scan  line  must  contain  an  even  number  of 
bytes,  however,  you  have  to  insert  a  0  after  each  byte: 

static  unsigned  char  cBrickBits  []  = 

{  0xFF,  0,  0x0C ,  0,  0X0C ,  0,  0x0C,  0, 

0xFF,  0,  0xC0 ,  0 ,  0xC0 ,  0,  0xC0,  0  }  ; 


Method  three 

This  method  is  similar  to  the  second  method  except  that  you  use  the  logical  bitmap  and 
logical  brush  structures  to  create  the  bitmap  and  the  brush.  Begin  by  defining  these 
variables: 

HBITMAP  hBitmap  ; 

HBRUSH  hBrush  ; 

static  BITMAP  bitmap  =  {  0,  8,  8,  2,  1,  1  }  ; 
static  LOGBRUSH  logbrush  =  {  BS.PATTERN,  0L  }  ; 
static  WORD  wBrickBits  []  = 

{  0xFF,  0x0C ,  0x0C ,  0x0C ,  0xFF,  0xC0,  0xC0,  0xC0  }  ; 

The  last  field  of  the  logical  bitmap  structure  remains  uninitialized.  This  field  must 
contain  a  far  pointer  to  the  array  of  bytes  that  define  the  bitmap  pattern.  Do  not  initialize 
the  structure  with  this  pointer,  however.  Instead  use  an  assignment  statement: 

bitmap. bmBi ts  =  ( LPSTR)  wBrickBits  ; 

Watch  out  when  you  assign  a  far  address  of  a  local  data  item  to  the  field  of  a  structure.  If  the 
program  is  running  in  real  mode  under  Windows  3.0  and  the  program’s  data  segment  is 
moved  in  memory  (as  it  can  be  following  a  GetMessage,  LocalAlloc ,  or  LocalReAlloc  call), 
that  far  address  can  become  invalid.  A  good  rule  is  to  make  this  assignment  just  before 
using  the  structure.  After  the  assignment,  you  use  this  structure  to  create  the  bitmap: 

hBitmap  =  CreateBi tmaplndi rect  ( &bi tmap )  ; 

Now  that  you  have  the  handle  to  a  bitmap,  you  can  use  the  CreateBrush Indirect  function 
to  create  the  brush: 

logbrush. lbHatch  =  hBitmap  ; 

hBrush  =  CreateBrushlndi rect  ( &1 ogbrush )  ; 

SelectObject  (hdc,  hBrush)  ; 

Rectangle  (hdc,  xLeft,  yTop,  xRight,  yBottom)  ; 

Later  on,  delete  both  the  brush  and  the  bitmap: 

DeleteObject  (hBrush)  ; 

DeleteObject  (hBitmap)  ; 
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Brush  Alignment 

When  Windows  fills  in  an  area  with  a  brush,  it  repeats  the  8-by-8  bitmap  both  horizontally 
and  vertically.  This  brush’s  appearance  can  vary  slightly,  depending  on  how  Windows 
aligns  the  upper  left  corner  of  the  bitmap  with  the  display  surface.  The  attribute  in  the  de¬ 
vice  context  that  determines  this  alignment  is  called  the  “brush  origin.”  This  attribute  is  al¬ 
ways  expressed  in  terms  of  screen  coordinates.  If  you  obtain  a  device  context  using 
BeginPaint  or  GetDC,  the  brush  origin  is  initially  set  to  the  upper  left  corner  of  your  win¬ 
dow’s  client  area.  If  the  client  area  begins  30  pixels  from  the  left  of  the  screen  and  20  pixels 
from  the  top  of  the  screen,  the  brush  origin  is  set  to  the  point  (30,  20). 

Whenever  Windows  uses  a  brush  within  the  client  area,  the  upper  left  corner  of  the 
brush’s  bitmap  coincides  with  those  client-area  device  points  where  both  x  and  y  are  mul¬ 
tiples  of  8.  Let’s  take  an  example  involving  a  hatch  brush  with  style  HS_FDIAGONAL, 
which  looks  like  this: 


In  MM-TEXT  mode,  when  you  draw  a  rectangle  that  is  filled  in  with  the  HS_FDIAGONAL 
brush,  the  downward  hatch  line  will  intersect  the  upper  left  corner  of  the  rectangle  if  this 
corner  is  at  the  logical  point  (8,  8).  However,  the  hatch  line  will  be  aligned  4  pixels  from  the 
top  of  the  corner  if  the  rectangle  begins  at  the  logical  point  (8,  4). 

In  most  cases,  adjusting  the  brush  origin  is  an  unnecessary  refinement  to  your  draw¬ 
ing,  but  sometimes  you’ll  want  to  do  it.  The  process  involves  three  steps: 

1.  Call  UnrealizeObjectiox  the  brush.  (Do  not  call  UnrealizeObject  for  stock 
brushes.) 

2.  Set  the  brush  origin  with  SetBrushOrg ,  remembering  to  use  screen 
coordinates. 


580 


Chapter  12:  Drawing  Graphics 


3.  Select  the  brush  into  the  device  context  using  SelectObject. 

One  situation  in  which  you’ll  need  to  change  the  brush  origin  is  when  you  want  the 
background  of  a  child  window  to  blend  in  with  the  background  of  its  parent  window. 
When  you  obtain  a  handle  to  the  device  context  for  the  child  window,  the  brush  origin  will 
be  the  upper  left  corner  of  the  child  window.  You  need  to  change  the  brush  origin  to  be  the 
upper  left  corner  of  the  parent  window.  (We  did  this  when  coloring  child  window  controls 
in  Chapter  6.)  In  this  case,  you’re  changing  the  brush  origin  in  one  device  context  so  that  it 
coincides  with  the  brush  origin  in  another  device  context. 

You’ll  also  need  to  change  brush  origins  when  you  draw  several  figures  sharing  the 
same  device  context  but  you  don’t  want  the  brushes  to  coincide.  For  instance,  suppose  you 
want  to  use  brushes  to  color  the  bars  of  a  bar  chart.  If  you  didn’t  care  about  brush  align¬ 
ment,  you  might  draw  each  of  the  bars  using  a  function  that  looks  like  this: 


void  DrawBarl 
HDC 
short 
HBRUSH 
{ 

HBRUSH 


(hdc,  xLeft,  yTop,  xRight,  yBottom,  hBrush) 
hdc  ; 

xLeft,  yTop,  xRight,  yBottom  ; 
hBrush  ; 

hBrushOriginal  ; 


hBrushOriginal  =  SelectObject  (hdc,  hBrush)  ; 

Rectangle  (hdc,  xLeft,  yTop,  xRight,  yBottom)  ; 

SelectObject  (hdc,  hBrushOriginal)  ; 

} 

This  function  simply  selects  the  brush  handle  passed  as  a  function  parameter  (saving  the 
handle  to  the  brush  originally  selected),  draws  a  rectangle,  and  then  selects  the  original 
brush  back  into  the  device  context.  If  a  program  used  this  routine  to  draw  several  adjacent 
bars  that  it  filled  in  with  the  HS_BDI  AGONAL  brush,  the  result  would  look  like  Figure  12-15. 
Notice  that  the  hatch  lines  for  all  three  bars  align,  which  has  the  unfortunate  effect  of  draw¬ 
ing  the  eye  downward  from  right  to  left. 


Figure  1 2-15.  Three  bars  that  have  the  same  device  context  and  brush  origin. 
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To  avoid  this  effect,  you  need  to  align  the  brush  with  each  bar  individually,  which  you 
can  accomplish  with  the  following  function: 

void  DrawBar2  (hwnd,  hdc,  xLeft,  yTop,  xRight,  yBottom,  hBrush) 

HWND  hwnd  ; 

HDC  hdc  ; 

short  xLeft,  yTop,  xRight,  yBottom  ; 

HBRUSH  hBrush  ; 

{ 

HBRUSH  hBrushOriginal  ; 

POINT  pt  ; 

Unreal izeObject  (hBrush)  ; 

pt.x  =  xLeft  ; 
pt.y  =  yTop  ; 

LPtoDP  (hdc,  &pt,  1)  ; 

ClientToScreen  (hwnd,  &pt)  ; 

SetBrushOrg  (hdc,  pt.x,  pt.y)  ; 

hBrushOriginal  =  SelectObject  (hdc,  hBrush)  ; 

Rectangle  (hdc,  xLeft,  yTop,  xRight,  yBottom)  ; 

SelectObject  (hdc,  hBrushOriginal)  ; 

} 

You  “unrealize”  the  brush  by  calling  UnrealizeObject  and  then  set  the  brush  origin  to  the 
upper  left  corner  of  the  bar  that’s  being  drawn.  This  requires  translating  the  upper  left  cor¬ 
ner  of  the  bar  to  client-area  coordinates  using  LPtoDP  and  then  to  screen  coordinates  using 
ClientToScreen.  The  result  is  shown  in  Figure  12-16.  Now  the  hatch  lines  are  drawn  begin¬ 
ning  from  the  upper  left  corner  of  each  bar  and  do  not  align  from  one  bar  to  the  next. 


Figure  1 2-16.  Three  bars  that  have  the  same  device  context  but  a  different  brush  origin. 
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RECTANGLES,  REGIONS,  AND  CLIPPING 

Windows  includes  several  additional  drawing  functions  that  work  with  RECT  (rectangle) 
structures  and  “regions.”  A  region  is  an  area  of  the  screen  that  is  a  combination  of  rect¬ 
angles,  other  polygons,  and  ellipses. 

Working  with  Rectangles 

These  three  drawing  functions  require  a  pointer  to  a  rectangle  structure: 

Fill Rect  (hdc,  &rect,  hBrush)  ; 

FrameRect  (hdc,  &rect,  hBrush)  ; 

InvertRect  (hdc,  &rect)  ; 

In  these  functions,  the  rect  parameter  is  a  structure  of  type  RECT  with  four  fields:  left ,  top, 
right ,  and  bottom.  The  coordinates  in  this  structure  are  treated  as  logical  coordinates. 

FillRect  fills  the  rectangle  (up  to  but  not  including  the  right  and  bottom  coordinates) 
with  the  specified  brush.  This  function  doesn’t  require  that  you  first  select  the  brush  into 
the  device  context.  We  used  the  FillRect  function  in  the  ROP2LOOK  program  earlier  in  this 
chapter  to  color  the  background  with  five  stock  brushes. 

FrameRect  uses  the  brush  to  draw  a  rectangular  frame,  but  it  does  not  fill  in  the 
rectangle.  Using  a  brush  to  draw  a  frame  may  seem  a  little  strange,  because  with  the  func¬ 
tions  that  you’ve  seen  so  far  (such  as  Rectangle ),  the  border  is  drawn  with  the  current  pen. 
FrameRect  allows  you  to  draw  a  rectangular  frame  that  isn’t  necessarily  a  pure  color.  This 
frame  is  one  logical  unit  wide.  If  logical  units  are  larger  than  device  units,  then  the  frame 
will  be  2  or  more  pixels  wide. 

InvertRect  inverts  all  the  pixels  in  the  rectangle,  turning  ones  to  zeros  and  zeros  to 
ones.  This  function  turns  a  white  area  to  black,  a  black  area  to  white,  and  a  green  area 
to  magenta. 

Windows  also  includes  nine  functions  that  allow  you  to  manipulate  RECT  structures 
easily  and  cleanly.  For  instance,  to  set  the  four  fields  of  a  RECT  structure  to  particular 
values,  you  would  conventionally  use  code  that  looks  like  this: 

rect. left  =  xLeft  ; 

rect. top  =  xTop  ; 

rect. right  =  xRight  ; 
rect. bottom  =  xBottom  ; 

By  calling  the  SetRect function,  however,  you  can  achieve  the  same  result  with  a  single  line: 

SetRect  (&rect,  xLeft,  yTop,  xRight,  yBottom)  ; 

The  other  eight  functions  can  also  come  in  handy  when  you  want  to  do  one  of  the 
following: 

■  Move  a  rectangle  a  number  of  units  along  the  xand  y  axes: 

OffsetRect  (&rect,  x,  y)  ; 
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■  Increase  or  decrease  the  size  of  a  rectangle: 

InflateRect  (&rect,  x,  y)  ; 

■  Set  the  fields  of  a  rectangle  equal  to  0: 

SetRectEmpty  (&rect)  ; 

■  Copy  one  rectangle  to  another: 

CopyRect  UDestRect,  &SrcRect)  ; 

■  Obtain  the  intersection  of  two  rectangles: 

IntersectRect  (&DestRect,  &SrcRectl,  &SrcRect2)  ; 

■  Obtain  the  union  of  two  rectangles: 

UnionRect  (&DestRect,  &SrcRectl,  &SrcRect2)  ; 

■  Determine  if  a  rectangle  is  empty: 

bEmpty  =  IsRectEmpty  (&rect)  ; 

■  Determine  if  a  point  is  in  a  rectangle: 

blnRect  =  PtlnRect  (&rect,  point)  ; 

In  most  cases,  the  equivalent  code  for  these  functions  is  simple.  Sometimes,  you’ll 
find  that  using  one  of  these  functions  actually  increases  the  size  of  your  .EXE  file.  In  some 
instances,  in  fact,  equivalent  code  takes  up  even  less  space  in  your  source  code  file.  For  ex¬ 
ample,  you  can  duplicate  the  CopyRect  function  call  with: 

DestRect  =  SrcRect  ; 

Creating  and  Painting  Regions 

A  region  is  a  description  of  an  area  of  the  display  that  is  a  combination  of  rectangles,  other 
polygons,  and  ellipses.  You  can  use  regions  for  drawing  or  for  clipping.  You  use  a  region 
for  clipping  by  selecting  the  region  into  the  device  context. 

Like  pens,  brushes,  and  bitmaps,  regions  are  GDI  objects.  Delete  any  regions  that  you 
create  by  calling  DeleteObject. 

When  you  create  a  region,  Windows  returns  a  handle  to  the  region  of  type  HRGN. 
The  simplest  type  of  region  describes  a  rectangle.  You  can  create  a  rectangular  region  in 
one  of  two  ways: 

hRgn  =  CreateRectRgn  (xLeft,  yTop,  xRight,  yBottom)  ; 
or: 

hRgn  =  CreateRectRgnlndi rect  (&rect)  ; 
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You  can  also  create  elliptical  regions  using: 

hRgn  =  CreateEl 1 ipticRgn  (xLeft,  yTop,  xRight,  yBottom)  ; 


or: 

hRgn  =  CreateEl 1 ipticRgnlndi rect  (&rect)  ; 

The  CreateRoundRectRgn  creates  a  rectangular  region  with  rounded  corners. 

Creating  a  polygonal  region  is  similar  to  using  the  Polygon  function: 

hRgn  =  CreatePolygonRgn  (&point,  nCount,  nPolyFil 1  Mode)  ; 

The  point  parameter  is  an  array  of  structures  of  type  POINT,  nCount  is  the  number  of 
points,  and  nPolyFillMode  is  either  ALTERNATE  or  WINDING.  You  can  also  create  mul¬ 
tiple  polygonal  regions  using  CreatePolyPolygonRgn . 

So  what,  you  say?  What  makes  these  regions  so  special?  Here’s  the  function  that 
unleashes  the  power  of  regions: 

nRgnType  =  CombineRgn  (hDestRgn,  hSrcRgnl,  hSrcRgn2,  nCombine)  ; 

This  combines  two  source  regions  ( hSrcRgnl  and  hSrcRgn2')  and  causes  the  destination 
region  handle  ( hDestRgn )  to  refer  to  that  combined  region.  All  three  region  handles  must 
be  valid,  but  the  region  previously  described  by  hDestRgn  is  destroyed.  (When  you  use  this 
function,  you  might  want  to  make  hDestRgn  refer  initially  to  a  small  rectangular  region.) 

The  nCombine  parameter  describes  how  the  hSrcRgnl  and  hSrcRgn2  regions  are  to 
be  combined: 


nCombine  Value 

New  Region 

RGN-AND 

Overlapping  area  of  the  two  source  regions 

RGN-OR 

All  the  two  source  regions 

RGN-XOR 

All  the  two  source  regions  excluding  the  overlapping  area 

RGN-DIFF 

All  of  hSrcRgnl  not  in  hSrcRgn2 

RGN-COPY 

The  hSrcRgnl  made  the  same  as  hSrcRgn2 

The  nRgnType  value  returned  from  CombineRgn  is  one  of  the  following:  NULLREGION, 
indicating  an  empty  region;  SIMPLEREGION,  indicating  a  simple  rectangle,  ellipse,  or 
polygon;  COMPLEXREGION,  indicating  a  combination  of  rectangles,  ellipses,  or  polygons; 
and  ERROR,  meaning  that  an  error  has  occurred. 

Once  you  have  a  handle  to  a  region,  you  can  use  it  with  four  drawing  functions: 

FillRgn  (hdc,  hRgn,  hBrush)  ; 

FrameRgn  (hdc,  hRgn,  hBrush,  xFrame,  yFrame)  ; 

InvertRgn  (hdc,  hRgn)  ; 

PaintRgn  (hdc,  hRgn)  ; 


585 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


The  FillRgn,  FrameRgn ,  and  InvertRgn  functions  are  similar  to  the  FillRect ,  FrameRect ,  and 
InvertRect  functions.  The  xFrame  and  yFrame  parameters  to  FrameRgn  are  the  logical 
width  and  height  of  the  frame  to  be  painted  around  the  region.  The  PaintRgn  function  fills 
in  the  region  with  the  brush  currently  selected  in  the  device  context.  All  these  functions 
assume  the  region  is  defined  in  logical  coordinates. 

When  you’re  finished  with  a  region,  you  can  delete  it  using  the  same  function  that  de¬ 
letes  other  GDI  objects: 

DeleteObject  (hRgn)  ; 

Clipping  with  Rectangles  and  Regions 

Regions  can  also  play  a  role  in  clipping.  (I  discussed  clipping  in  Chapter  2  when  discussing 
the  various  SYSMETS  programs.)  The  InvalidateRect  function  invalidates  a  rectangular 
area  of  the  display  and  generates  a  WM -PAINT  message.  Often  we  use  the  InvalidateRect 
function  to  erase  the  client  area  and  generate  a  WM -PAINT  message: 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 

You  can  obtain  the  coordinates  of  the  invalid  rectangle  by  calling  GetUpdateRect,  and  you 
can  validate  a  rectangle  of  the  client  area  using  the  ValidateRect  function.  When  you 
receive  a  WM-PAINT  message,  the  coordinates  of  the  invalid  rectangle  are  available  from 
the  PAINTSTRUCT  structure  that  is  filled  in  by  the  BeginPaint  function.  This  invalid  rect¬ 
angle  also  defines  a  “clipping  region.”  You  cannot  paint  outside  the  clipping  region. 

Windows  has  two  functions  similar  to  InvalidateRect  and  ValidateRect  that  work  with 
regions  rather  than  rectangles: 

InvalidateRgn  (hwnd,  hRgn,  bErase)  ; 

and: 


ValidateRgn  (hwnd,  hRgn)  ; 

When  you  receive  a  WM-PAINT  message  as  a  result  of  an  invalid  region,  the  clipping 
region  will  be  a  region  that  is  not  necessarily  rectangular. 

You  can  create  a  clipping  region  of  your  own  by  selecting  a  region  into  the  device 
context  using  either: 

SelectObject  (hdc,  hRgn)  ; 


or: 


SelectCl ipRgn  (hdc,  hRgn)  ; 

A  clipping  region  is  assumed  to  be  in  device  coordinates. 
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GDI  makes  a  copy  of  the  clipping  region,  so  you  can  delete  the  region  after  you  select  it  in 
the  device  context.  Windows  also  includes  several  functions  to  manipulate  this  clipping 
region,  such  as  ExcludeClipRect  to  exclude  a  rectangle  from  the  clipping  region,  Inter- 
sectClipRect  to  create  a  new  clipping  region  that  is  the  intersection  of  the  previous  clipping 
region  and  a  rectangle,  and  OffsetClipRgn  to  move  a  clipping  region  to  another  part  of  the 
client  area. 

The  CLOVER  Program 

The  CLOVER  program  forms  a  region  out  of  four  ellipses,  selects  this  region  into  the  device 
context,  and  then  draws  a  series  of  lines  emanating  from  the  center  of  the  window’s  client 
area.  The  lines  appear  only  in  the  area  defined  by  the  region.  The  resulting  display  is 
shown  in  Figure  12-17. 

To  draw  this  graphic  by  conventional  methods,  you  would  have  to  calculate  the  end 
point  of  each  line  based  on  formulas  involving  the  circumference  of  an  ellipse.  By  using  a 
complex  clipping  region,  you  can  draw  the  lines  and  let  Windows  determine  the  end 
points.  The  CLOVER  program  is  shown  in  Figure  12-18,  beginning  on  the  following  page. 


Figure  12-17.  The  CLOVER  display,  drawn  using  a  complex  clipping  region. 
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CLOVER.MAK 

//- . - . 

//  CLOVER.MAK  make  file 
# . 

clover.exe  :  clover. obj  clover. def 

$ ( WI N LI NK)  clover,  clover,  NUL,  $(WINLIB),  clover 
rc  -t  clover.exe 

clover. obj  :  clover. c 
$ ( W I NCC )  clover. c 


CLOVER.C 

/* . 

CLOVER.C  --  Clover  Drawing  Program  Using  Regions 
(c)  Charles  Petzold,  1992 

. - . */ 


#include  <windows.h> 

//include  <math.h> 

//define  TW0_PI  (2.0  *  3.14159) 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Clover"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. IpszMenuName 
wndclass. IpszClassName 


=  CS.HREDRAW  !  CS.VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL,  IDC.ARR0W)  ; 
=  GetStockObject  (WHITE.BRUSH)  ; 
=  NULL  ; 

=  szAppName  ; 


Figure  12-18.  The  CLOVER  program. 


(continued) 
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RegisterClass  ,( &wndcl ass )  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Draw  a  Clover", 

WS_OVERLAPPEDWINDOW, 

CW_USEDEFAULTf  CW.USEDEFAULT, 

COSEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  : 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HRGN  hRgnClip  ; 
static  short  cxClient,  cyClient  ; 
double  fAngle,  f Radi  us  ; 

HCURSOR  hCursor  ; 

HDC  hdc  ; 

HRGN  hRgnTemp  [6]  ; 

PAINTSTRUCT  ps  ; 
short  i  ; 

switch  (message) 

{ 

case  WM.SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 

cyClient  =  HIWORD  (IParam)  ; 

hCursor  =  SetCursor  (LoadCursor  (NULL,  IDC.WAIT))  ; 

ShowCursor  (TRUE)  ; 

if  (hRgnClip) 

DeleteObject  (hRgnClip)  ; 

hRgnTemp  [0]  =  CreateEl 1 i pti cRgn  (0,  cyClient  /  3, 

cxClient  /  2,  2  *  cyClient  /  3)  ; 
hRgnTemp  [1]  =  CreateEl 1 i pti cRgn  (cxClient  /  2,  cyClient  /  3, 

cxClient,  2  *  cyClient  /  3)  ; 


(continued) 
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hRgnTemp  [2]  =  CreateEll ipticRgn  (cxClient  /  3,  0, 

2  *  cxClient  /  3,  cyClient  /  2)  ; 
hRgnTemp  [3]  =  CreateEl 1 i pti cRgn  (cxClient  /  3,  cyClient  /  2, 

2  *  cxClient  /  3,  cyClient)  ; 
hRgnTemp  [4]  =  CreateRectRgn  (0,  0,  1,  1)  ; 

hRgnTemp  [5]  =  CreateRectRgn  (0,  0,  1,  1)  ; 

hRgnClip  =  CreateRectRgn  (0,  0,  1,  1)  ; 

Combi neRgn  (hRgnTemp  [4],  hRgnTemp  [0],  hRgnTemp  [1],  RGN_0R) 

CombineRgn  (hRgnTemp  [5],  hRgnTemp  [2],  hRgnTemp  [3],  RGN_0R) 

CombineRgn  (hRgnClip,  hRgnTemp  [4],  hRgnTemp  [5],  RGN_X0R) 

for  (i  =  0  ;  i  <  6  ;  i++) 

DeleteObject  (hRgnTemp  [i ] )  ; 

SetCursor  (hCursor)  ; 

ShowCursor  (FALSE)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SetViewportOrg  (hdc,  cxClient  /  2,  cyClient  /  2)  ; 
SelectClipRgn  (hdc,  hRgnClip)  ; 

fRadius  =  hypot  (cxClient  /  2.0,  cyClient  /  2.0)  ; 

for  (fAngle  =  0.0  ;  fAngle  <  TW0_PI  ;  fAngle  +=  TWO.PI  /  360) 

{ 

MoveTo  (hdc,  0,  0)  ; 

LineTo  (hdc,  (short)  (  fRadius  *  cos  (fAngle)  +  0.5), 
(short)  (-fRadius  *  sin  (fAngle)  +  0.5))  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM.DESTROY  : 

DeleteObject  (hRgnClip)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
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CLOVER.DEF 


CLOVER. DEF  module  definition  file 


NAME 


CLOVER 


DESCRIPTION  ’Clover  Drawing  Using  Regions  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  ’WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


Because  regions  always  use  device  coordinates,  the  CLOVER  program  has  to  re-create  the 
region  every  time  it  receives  a  WM_SIZE  message.  This  may  require  several  seconds. 
CLOVER  begins  by  creating  four  elliptical  regions  that  are  stored  as  the  first  four  elements 
of  the  hRgnTemp  array .  Then  the  program  creates  three  “dummy”  regions: 

hRgnTemp  [4]  =  CreateRectRgn  (0,  0,  1,  1)  ; 

hRgnTemp  [5]  =  CreateRectRgn  (0,  0,  1,  1)  ; 

hRgnClip  =  CreateRectRgn  (0,  0,  1,  1)  ; 

The  two  elliptical  regions  at  the  left  and  right  of  the  client  area  are  combined: 

CombineRgn  (hRgnTemp  [4],  hRgnTemp  [0],  hRgnTemp  [1],  RGN_0R)  ; 

Similarly,  the  two  elliptical  regions  at  the  top  and  bottom  of  the  client  area  are  combined: 

CombineRgn  (hRgnTemp  [5],  hRgnTemp  [2],  hRgnTemp  [3],  RGN_0R)  ; 

Finally,  these  two  combined  regions  are  in  turn  combined  into  hRgnClip : 

CombineRgn  (hRgnClip,  hRgnTemp  [4],  hRgnTemp  [5],  RGN_X0R)  ; 

The  RGN_XOR  identifier  is  used  to  exclude  overlapping  areas  from  the  resultant  region. 
Finally,  the  six  temporary  regions  are  deleted: 

for  (i  =  0  ;  i  <  6  ;  i++) 

DeleteObject  (hRgnTemp  [i ] )  ; 

The  WM _PAINT  processing  is  simple,  considering  the  results.  The  viewport  origin  is 
set  to  the  center  of  the  client  area  (to  make  the  line  drawing  easier),  and  the  region  created 
during  the  WM-SIZE  message  is  selected  as  the  device  context’s  clipping  region: 

SetViewportOrg  (hdc,  xClient  /  2,  yClient  /  2)  ; 

SelectCl ipRgn  (hdc,  hRgnClip)  ; 
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Now  all  that’s  left  is  drawing  the  lines — 360  of  them,  spaced  1  degree  apart.  The 
length  of  each  line  is  the  variable  / Radius ,  which  is  the  distance  from  the  center  to  the 
corner  of  the  client  area: 

fRadius  =  hypot  (xClient  /  2.0,  yClient  /  2.0)  ; 

for  (fAngle  =  0.0  ;  fAngle  <  TWCLPI  ;  fAngle  +=  TW0_P I  /  360) 

{ 

MoveTo  (hdc,  0,  0)  ; 

LineTo  (hdc,  (short)  (  fRadius  *  cos  (fAngle)  +  0.5), 

(short)  (-fRadius  *  sin  (fAngle)  +  0.5))  ; 

} 

During  processing  of  WM -DESTROY,  the  region  is  deleted: 

DeleteObject  (hRgnClip)  ; 


SOME  MISCELLANEOUS  GDI  FUNCTIONS 

A  few  additional  drawing  functions  don’t  fit  into  any  convenient  categories.  These  include 
FloodFill ,  Drawlcon,  ScrollWindow,  ScrollDC ,  LineDDA,  and  LineProc. 

FloodFill fills  in  an  area  with  the  current  brush.  The  syntax  is: 

FloodFill  (hdc,  xStart,  yStart,  rgbColor)  ; 

This  is  the  function  that  the  Windows  PAINTBRUSH  program  calls  when  you  use  the 
“paint  roller”  icon.  Starting  at  the  logical  point  ( xStart ,  yStart ),  the  function  fills  in  an  area 
until  it  encounters  a  boundary  of  rgbColor. 

FloodFill  doesn’t  work  if  the  point  C xStart ,  yStart)  is  rgbColor  itself  or  if  the  point  is 
outside  the  clipping  region.  If  you  use  FloodFill  during  normal  repainting  of  your  client 
area,  you  might  want  to  invalidate  the  entire  client  area  before  calling  BeginPaint  to  be 
sure  that  ( xStart ,  yStart)  is  in  the  clipping  region. 

The  ExtFloodFill  function  has  the  following  syntax: 

ExtFloodFill  (hdc,  xStart,  yStart,  rgbColor,  wFill)  ; 

ExtFloodFill  is  an  extended  version  of  FloodFill  that  (depending  on  the  last  parameter) 
can  fill  to  a  boundary  or  over  a  surface  the  color  of  rgbColor. 

Drawlcon  draws  an  icon  on  the  display: 

Drawlcon  (hdc,  xStart,  yStart,  hlcon)  ; 

This  function  works  only  in  the  MM -TEXT  mapping  mode.  (The  Drawlcon  function 
appears  in  Chapter  9.) 

Both  ScrollWindow  and  ScrollDC  scroll  part  of  the  window’s  client  area.  We  used 
ScrollWindow  in  the  SYSMETS3  program  in  Chapter  2.  It’s  not  a  GDI  function,  so  it  always 
uses  device  units.  The  general  syntax  is: 

ScrollWindow  (hwnd,  xScroll,  yScroll,  ArectScroll,  &rectCl ip)  ; 
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Note  that  the  first  parameter  is  a  handle  to  a  window  rather  than  to  a  device  context.  The 
section  of  the  client  area  indicated  by  the  rectScroll  rectangle  structure  is  shifted  right 
xScroll  pixels  and  down  yScroll  pixels.  These  two  parameters  can  be  negative  if  you  use 
the  function  to  scroll  to  the  left  or  up. 

Only  the  area  within  the  rectClip  rectangle  is  affected  by  this  scrolling,  so  it  makes 
sense  to  set  rectClip  to  be  either  the  same  rectangle  as  rectScroll ,  a  larger  rectangle,  or 
NULL.  If  you  want  the  area  within  rectScroll  to  be  scrolled  without  affecting  anything  out¬ 
side  the  rectangle,  set  rectClip  to  equal  rectScroll.  If  it  is  acceptable  for  the  area  within 
rectScroll  to  be  shifted  outside  the  rectangle,  set  rectClip  to  NULL.  The  area  uncovered  by 
the  scrolling  is  invalidated  and  generates  a  WM-PAINT  message.  Because  ScrollWindow is 
not  a  GDI  function,  it  can’t  perform  clipping  and  will  also  scroll  dialog  boxes  or  child  win¬ 
dows  that  may  be  covering  the  surface  of  the  client  area. 

ScrollDCis  a  GDI  function  and  works  differently.  The  syntax  is: 

ScrollDC  (hdc,  xScroll,  yScroll,  &rectScroll,  &rectClip, 
hRgnUpdate,  &rectUpdate)  ; 

When  not  set  to  NULL,  the  last  two  parameters  return  information  to  the  program.  If  you 
pass  a  region  handle  to  Windows  in  the  sixth  parameter,  Windows  sets  the  region  to  the  in¬ 
valid  region  uncovered  by  the  scroll.  If  you  pass  a  pointer  to  a  RECT  structure  in  the  last  pa¬ 
rameter,  Windows  sets  the  structure  to  indicate  the  invalid  rectangle  uncovered  by  the 
scroll. 

The  LineDDA  function  calculates  all  the  points  on  a  straight  line  that  connects  two 
given  points.  (DDA  stands  for  “digital  differential  analyzer.”)  The  syntax  is: 

LineDDA  (xStart,  yStart,  xEnd,  yEnd,  1 pfnLi neProc,  1  Data )  ; 

LineDDA  requires  a  call-back  function  of  the  form: 

void  FAR  PASCAL  _export  LineProc  (int  x,  int  y,  (LONG)  1  Data ) 

{ 

[other program  lines] 

} 

The  IpfnLineProc  parameter  you  pass  to  LineDDA  must  be  the  result  of  a  MakeProc- 
Instance  call: 

IpfnLineProc  =  MakeProcInstance  (LineProc,  hlnstance)  ; 

When  you  call  LineDDA ,  Windows  calls  LineProc  once  for  each  point  on  the  line  connect¬ 
ing  C xStart ,  yStart )  and  ( xEnd ,  yEnd).  The  point  is  indicated  by  the  x  and  y  parameters 
to  LineProc.  LineProc  also  receives  the  far  pointer  to  programmer-defined  data  that  you 
supply  in  the  LineDDA  call. 
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Note  that  LineDDA  does  not  require  a  handle  to  a  device  context.  The  function  is  sim¬ 
ply  a  line  calculation  algorithm  that  gives  your  program  each  point  it  calculates.  What  you 
do  with  these  points  is  up  to  you.  In  the  LINEDDA  program,  shown  in  Figure  12-19, 1  chose 
to  draw  a  rectangle  and  connect  the  corners  of  the  rectangle  with  the  corners  of  the  client 
area.  Not  satisfied  with  the  mundane  dotted  and  dashed  line  styles  that  Windows  allows 
one  to  use  with  more  ease,  I  chose  to  draw  the  lines  as  a  series  of  tiny  ellipses.  The  result  is 
shown  in  Figure  12-20  on  page  597. 

LINEDDA.MAK 

# . 

#  LINEDDA.MAK  make  file 

# 

linedda.exe  :  linedda.obj  linedda.def 

$(WINLINK)  linedda.  linedda,  NUL,  $(WINLIB),  linedda 
rc  -t  linedda.exe 

linedda.obj  :  linedda.c 
$ ( W I NCC )  linedda.c 


LINEDDA.C 


/* . 

LINEDDA.C  --  LineDDA  Demonstration 

(c)  Charles  Petzold,  1992 
. */ 


^include  <windows.h> 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 
void  FAR  PASCAL  .export  LineProc  (int,  i nt ,  LONG)  ; 

HANDLE  hlnst  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "LineDDA"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


Figure  12-19.  The  LINEDDA  program.  (continued) 
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if  ( IhPrevInstance) 

{ 

wndcl ass. style 

wndclass.lpfnWndProc 

wndclass.cbClsExtra 

wndclass.cbWndExtra 

wndclass. hlnstance 

wndclass.hlcon 

wndclass.hCursor 

wndclass.hbrBackground 

wndclass. IpszMenuName 

wndclass. IpszClassName 


CS.HREDRAW  !  CS_VREDRAW  ; 
WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

NULL  ; 

LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITE.BRUSH)  ; 
NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hlnst  =  hlnstance  ; 

hwnd  =  CreateWindow  (szAppName,  "LineDDA  Demonstration", 
WS.OVERLAPP EDWIN DOW, 

CW.USEDEFAULT,  CWJJSEDEFAULT, 
CW_USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL.  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  FARPROC  lpfnLineProc  ; 

static  short  cxClient,  cyClient,  xL,  xR,  yT,  yB  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

lpfnLineProc  =  MakeProcInstance  ((FARPROC)  LineProc,  hlnst)  ; 
return  0  ; 


(continued) 
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case  WM_SIZE  : 

xR  =  3  *  (xL  =  (cxClient  =  LOWORD  (lParam))  /  4)  ; 
yB  =  3  *  (yT  =  (cyClient  =  HIWORD  (lParam))  /  4)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 


LineDDA  (xL,  yT,  xR,  yT,  1 pfnLi neProc,  (LONG)  hdc) 
LineDDA  (xR,  yT,  xR,  yB,  lpfnLineProc,  (LONG)  hdc) 
LineDDA  (xR,  yB,  xL,  yB,  lpfnLineProc,  (LONG)  hdc) 
LineDDA  (xL,  yB,  xL,  yT,  lpfnLineProc,  (LONG)  hdc) 


LineDDA  (0,  0,  xL, 
LineDDA  (cxClient.  0,  xR, 
LineDDA  (cxClient,  cyClient.  xR, 
LineDDA  (0,  cyClient,  xL, 


yT,  lpfnLineProc,  (LONG)  hdc) 
yT,  lpfnLineProc,  (LONG)  hdc) 
yB,  lpfnLineProc,  (LONG)  hdc) 
yB,  lpfnLineProc,  (LONG)  hdc) 


EndPaint  (hwnd,  &ps)  ; 
return  0  ; 


case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd.  message,  wParam,  lParam)  ; 
} 


void  FAR  PASCAL  ^export  LineProc  (int  x,  int  y,  LONG  1  Data ) 

{ 

static  short  nCounter  =  0  ; 


if  (nCounter  ==  2) 

Ellipse  ((HDC)  1  Data .  x  -  2,  y  -  2,  x  +  3.  y  +  3)  ; 

nCounter  =  (nCounter  +  1)  %  4  ; 

} 


LINEDDA.DEF 


;  LINEDDA.DEF  module  definition  file 
NAME  LINEDDA 


(continued) 
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DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


’LineDDA  Demonstration  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


Figure  12-20.  The  LINEDDA  display. 

The  LineDDA  function  is  called  eight  times  during  processing  of  the  WM_PAINT  message, 
once  for  each  of  the  eight  lines.  The  IpData  parameter  is  the  address  of  the  handle  to  the 
device  context. 

The  LineProc  function  is  short: 

void  FAR  PASCAL  .export  LineProc  (int  x,  int  y,  (LONG)  1  Data ) 

{ 

static  short  nCounter  =  0  ; 
if  (nCounter  ==  2) 

Ellipse  ( ( HDC )  IData,  x  -  2,  y  -  2,  x  +  3,  y  +  3)  ; 

nCounter  =  (nCounter  +  1)  %  4  ; 

} 
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Note  that  the  nCounter  variable  is  defined  as  static  so  that  its  value  is  preserved  between 
LineProc  calls.  It  cycles  through  the  values  0,  1,  2,  and  3.  When  the  value  is  2,  LineProc 
draws  an  ellipse  centered  on  the  point. 


PROGRAMS  THAT  DRAW  FOREVER 

A  fun  program  in  any  graphics  system  is  one  that  runs  “forever,”  simply  drawing  a  hypnotic 
series  of  rectangles  with  random  sizes  and  colors.  You  can  create  such  a  program  in  Win¬ 
dows,  but  it’s  not  quite  as  easy  as  it  first  seems.  By  now  you  should  know  that  this  is  defi¬ 
nitely  not  the  way  to  do  it: 

case  WM_PAI NT  :  //  Very,  very  bad  code  !!! 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 


e  (TRUE) 

{ 

xLeft 

_ 

rand 

() 

% 

xCl i ent 

xRight 

= 

rand 

0 

% 

xCl ient 

yTop 

= 

rand 

0 

% 

yCl ient 

yBottom 

= 

rand 

() 

% 

yCl ient 

nRed 

= 

rand 

0 

& 

255  ; 

nGreen 

= 

rand 

() 

& 

255  ; 

nBl  ue 

= 

rand 

0 

& 

255  ; 

hdc  =  GetDC  (hwnd)  ; 

hBrush  =  CreateSol idBrush  (RGB  (nRed,  nGreen,  nBlue))  ; 

SelectObject  (hdc,  hBrush)  ; 

Rectangle  (hdc,  min  (xLeft,  xRight),  min  (yTop,  yBottom), 
max  (xLeft,  xRight),  max  (yTop,  yBottom))  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

Sure,  this  will  work,  but  nothing  else  will.  Because  Windows  is  a  nonpreemptive  multitask¬ 
ing  environment,  a  program  can’t  enter  into  an  infinite  loop  like  this.  This  loop  will  stop  all 
other  processing  in  the  system. 

One  acceptable  alternative  is  setting  a  Windows  timer  to  send  WM -TIMER  messages 
to  your  window  function.  For  each  WM -TIMER  message,  you  obtain  a  device  context  with 
GetDC ,  draw  a  random  rectangle,  and  then  release  the  device  context  with  ReleaseDC.  But 
that  takes  some  of  the  fun  out  of  the  program,  because  the  program  can’t  draw  the  random 
rectangles  as  quickly  as  possible.  It  must  wait  for  each  WM -TIMER  message. 
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There  must  be  plenty  of  “dead  time”  in  Windows,  time  during  which  all  the  message 
queues  are  empty  and  Windows  is  just  sitting  in  a  little  loop  waiting  for  keyboard  or  mouse 
input.  Couldn’t  we  somehow  get  control  during  that  dead  time  and  draw  the  rectangles, 
relinquishing  control  only  when  a  message  is  added  to  a  program’s  message  queue?  That’s 
one  of  the  purposes  of  the  PeekMessage  function. 

Here’s  one  example  of  a  PeekMessage  c all: 

PeekMessage  (&msg,  NULL.  0.  0.  PM.REMOVE)  ; 

The  first  four  parameters  (a  pointer  to  a  MSG  structure,  a  window  handle,  and  two  values 
indicating  a  message  range)  are  identical  to  those  of  GetMessage.  Setting  the  second,  third, 
and  fourth  parameters  to  NULL  or  0  indicates  that  we  want  PeekMessage  to  return  all  mes¬ 
sages  for  all  windows  in  the  program.  Like  GetMessage ,  PeekMessage  effectively  yields  con¬ 
trol  to  other  programs  if  messages  are  waiting  in  the  other  programs’  message  queues.  Like 
GetMessage ,  PeekMessage  returns  messages  only  for  windows  created  by  the  program  that 
makes  the  function  call. 

The  last  parameter  to  PeekMessage  is  set  to  PM -REMOVE  if  the  message  is  to  be  re¬ 
moved  from  the  message  queue.  You  can  set  it  to  PM_NOREMOVE  if  the  message  isn’t  to  be 
removed.  This  is  why  PeekMessage  is  a  “peek”  rather  than  a  “get” — it  allows  a  program  to 
check  the  next  message  in  the  program’s  queue  without  actually  removing  it.  GetMessage 
doesn’t  return  control  to  a  program  unless  it  retrieves  a  message  from  the  program’s  mes¬ 
sage  queue.  But  PeekMessage  will  return  under  two  conditions: 

■  When  there’s  a  message  in  the  program’s  message  queue,  in  which  case 
the  return  value  of  PeekMessage  is  TRUE  (nonzero). 

■  When  there  are  no  messages  in  the  message  queue  of  any  program 
running  under  Windows,  in  which  case  the  return  value  of  PeekMessage  is 
FALSE  (0). 

A  message  loop  that  uses  PeekMessage  rather  than  GetMessage  essentially  says  to  Win¬ 
dows,  “Let  other  programs  run  for  a  little  while,  but  once  they’ve  emptied  their  message 
queues,  return  control  to  me — I’m  not  finished  with  my  work.”  If  two  or  more  programs 
are  running  that  use  a  PeekMessage  loop  to  retrieve  messages,  Windows  uses  a  round-robin 
approach,  returning  control  sequentially  to  each  program  waiting  with  a  PeekMessage c all. 

This  allows  us  to  replace  the  normal  message  loop,  which  looks  like  this: 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 
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with  an  alternative  message  loop  like  this: 

while  (TRUE) 

{ 

if  (PeekMessage  (&msg,  NULL,  0,  0,  PM_REM0V E ) ) 

{ 

if  (msg. message  ==  WM_QUIT) 
break  ; 

Transl ateMessage  (&msg)  ; 

DispatchMessage  ( &msg )  ; 

} 

else 

{ 

[other  program  lines  to  do  some  work] 

} 

} 

return  msg.wParam  ; 

Notice  that  the  WM_QUIT  message  is  explicitly  checked.  You  don’t  have  to  do  this  in  a 
normal  message  loop,  because  the  return  value  of  GetMessage  is  0  when  it  retrieves  a 
WM-QUIT  message.  But  PeekMessage  uses  its  return  value  to  indicate  whether  a  message 
was  retrieved,  so  the  check  of  WM_QUIT  is  required. 

If  the  return  value  of  PeekMessage  is  TRUE,  the  message  is  processed  normally.  If  the 
value  is  FALSE,  the  program  can  do  some  work  (such  as  displaying  yet  another  random 
rectangle)  before  returning  control  to  Windows. 

(Although  the  Windows  documentation  notes  that  you  can’t  use  PeekMessage  to  re¬ 
move  WM -PAINT  messages  from  the  message  queue,  this  isn’t  really  a  problem.  After  all, 
GetMessage  doesn’t  remove  WM -PAINT  messages  from  the  queue  either.  The  only  way  to 
remove  a  WM-PAINT  message  from  the  queue  is  to  validate  the  invalid  regions  of  the  win¬ 
dow’s  client  area,  which  you  can  do  with  ValidateRect ,  ValidateRgn ,  or  a  BeginPaint  and 
EndPaint  pair.  If  you  process  a  WM-PAINT  message  normally  after  retrieving  it  from  the 
queue  with  PeekMessage ,  you’ll  have  no  problems.  What  you  can’t  do  is  use  code  like  this  to 
empty  your  message  queue  of  all  messages: 

while  (PeekMessage  (&msg,  NULL,  0,  0,  PM_REM0VE) )  ; 

This  statement  removes  and  discards  all  messages  from  your  message  queue  except 
WM_PAINT.  If  a  WM_PAINT  message  is  in  the  queue,  you’ll  be  stuck  inside  the  while 
loop  forever.) 

The  Windows  TERMINAL  program  uses  a  PeekMessage  loop  when  it  receives  input 
from  a  communications  line.  This  allows  TERMINAL  to  check  “continuously”  for  incom¬ 
ing  data.  The  PRINT  MANAGER  program  uses  this  technique  to  print  on  a  printer  or  plotter 
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and — as  you’ll  see  in  Chapter  15 — a  Windows  program  that  prints  also  includes  a  function 
with  a  PeekMessage  loop.  Armed  with  the  PeekMessage  function,  we  can  now  write  a 
program  that  relentlessly  displays  random  rectangles.  The  program,  called  RANDRECT, 
is  shown  in  Figure  12-21. 


RANDRECT.MAK 

# . - . 

#  RANDRECT.MAK  make  file 

# 

randrect.exe  :  randrect.obj  randrect.def 

$( WINLINK)  randrect,  randrect,  NUL.  $(WINLIB),  randrect 
rc  -t  randrect.exe 

randrect.obj  :  randrect. c 
$ ( W I NCC )  randrect. c 


RANDRECT.C 

/*-  -  - . 

RANDRECT.C  --  Displays  Random  Rectangles 
(c)  Charles  Petzold,  1992 
. */ 


#include  <windows.h> 

^include  <stdlib.h> 

#define  min(a.b)  (((a)  <  (b))  ?  (a)  :  (b)) 

#define  max(a.b)  (((a)  >  (b))  ?  (a)  :  (b) ) 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 
void  DrawRectangle  (HWND)  ; 

short  cxClient.  cyClient  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine.  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "RandRect”  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


Figure  12-21.  The  RANDRECT  program. 


(continued) 


601 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


if  ( IhPrevInstance) 

{ 

wndcl ass. style 
wndclass.lpfnWndProc 
wndcl ass. cbClsExtra 
wndcl ass. cbWndExtra 
wndclass.hlnstance 
wndclass.hlcon 
wndclass.hCursor 
wndcl ass. hbrBackg round 
wndcl ass. IpszMenuName 
wndcl ass. IpszClassName 


=  CS_HREDRAW  !  CS_VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL.  IDC_ARR0W)  ; 
=  GetStockObject  (WHITEJ3RUSH)  ; 
=  NULL  ; 

=  szAppName  ; 


! Regi sterCl ass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "Random  Rectangles". 

WS_0V  ERLAPPEDWI NDOW . 

CW_USEDE FAULT,  CW_USEDE FAU LT , 
CW.USEDEFAULT,  CW_USEDEFAULT, 
NULL.  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (TRUE) 

{ 

if  (PeekMessage  (&msg,  NULL,  0,  0,  PM_REM0VE) ) 

{ 

if  (msg. message  ==  WM_QUIT) 
break  ; 


TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

else 


DrawRectangle  (hwnd)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM.SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HIWORD  (IParam)  ; 
return  0  ; 


(continued) 
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case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

void  DrawRectangle  ( HWND  hwnd) 

{ 

HBRUSH  hBrush  ; 

HDC  hdc  ; 

short  xLeft,  xRight,  yTop,  yBottom,  nRed,  nGreen,  nBlue  ; 

xLeft  =  rand  0  %  cxClient  ; 

xRight  =  rand  0  %  cxClient  ; 

yTop  =  rand  0  %  cyClient  ; 

yBottom  =  rand  0  %  cyClient  ; 

nRed  =  rand  0  &  255  ; 

nGreen  =  rand  0  &  255  ; 

nBlue  =  rand  0  &  255  ; 

hdc  =  GetDC  (hwnd)  ; 

hBrush  =  CreateSol idBrush  (RGB  (nRed,  nGreen,  nBlue))  ; 
SelectObject  (hdc.  hBrush)  ; 

Rectangle  (hdc,  min  (xLeft,  xRight),  min  (yTop,  yBottom), 
max  (xLeft,  xRight),  max  (yTop,  yBottom))  ; 

ReleaseDC  (hwnd,  hdc)  ; 

DeleteObject  (hBrush)  ; 

} 


RANDRECT.DEF 


RANDRECT. DEF  module  definition  file 


NAME  RANDRECT 

DESCRIPTION  'Random  Rectangle  Drawing  Program  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 
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Bits,  Bits, 
and  Metafiles 


Bitmaps  and  metafiles  represent  two  very  different  ways  of  storing  pictorial  information. 
The  bitmap  is  a  complete  digital  representation  of  the  picture.  Each  pixel  in  the  image  cor¬ 
responds  to  one  or  more  bits  in  the  bitmap.  Monochrome  bitmaps  require  only  one  bit  per 
pixel;  color  bitmaps  require  additional  bits  to  indicate  the  color  of  each  pixel. 

A  metafile,  on  the  other  hand,  stores  pictorial  information  as  a  series  of  records  that 
correspond  directly  to  GDI  calls,  such  as  MoveTo,  Rectangle ,  TextOut,  and  others  that  you 
encountered  in  Chapter  12.  A  metafile  is  thus  a  description  of  a  picture  rather  than  a  digital 
representation  of  it. 

Both  bitmaps  and  metafiles  have  their  place  in  computer  graphics.  Bitmaps  are  very 
often  used  for  very  complex  images  originating  from  the  real  world,  such  as  digitized 
photographs.  Metafiles  are  more  suitable  for  human-  or  machine-generated  images,  such  as 
architectural  drawings.  Both  bitmaps  and  metafiles  can  exist  in  memory  or  be  stored  on  a 
disk  as  files,  and  both  can  be  transferred  among  Windows  applications  using  the  clipboard. 

You  can  construct  a  bitmap  “manually”  using  the  PAINTBRUSH  program  included 
with  Windows  3.1.  You  can  then  include  the  bitmap  as  a  resource  in  a  resource  script  file 
and  load  it  into  a  program  using  the  LoadBitmap  function.  This  was  demonstrated  in 
Chapter  8.  In  Chapter  9  we  saw  how  bitmaps  can  substitute  for  text  in  a  menu.  In  Chapter  12 
we  constructed  small  8-by-8-pixel  bitmaps  to  use  as  brushes. 

Metafiles  are  more  closely  associated  with  Windows  drawing  programs  (such  as 
Micrografx’s  Designer)  and  other  CAD  (computer-aided  design)  programs.  The  user  of 
these  programs  draws  an  image  with  lines,  rectangles,  ellipses,  text,  and  other  graphics 
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primitives.  Although  these  programs  generally  use  a  private  format  for  storing  the  picture 
in  a  file,  they  can  usually  transfer  the  picture  to  the  clipboard  in  the  form  of  a  metafile. 

Bitmaps  have  two  major  drawbacks.  First,  they  are  highly  susceptible  to  problems  in¬ 
volving  device  dependence.  The  most  obvious  device  dependency  is  color.  Displaying  a 
color  bitmap  on  a  monochrome  device  is  often  unsatisfactory.  Another  problem  is  that  a 
bitmap  implies  a  particular  resolution  and  aspect  ratio  of  an  image.  Although  bitmaps  can 
be  stretched  or  compressed,  this  process  generally  involves  duplicating  or  dropping  rows 
or  columns  of  pixels  and  can  lead  to  distortion  in  the  scaled  image.  A  metafile  can  be  scaled 
to  almost  any  size  without  distortion. 

The  second  major  drawback  of  bitmaps  is  that  they  require  a  large  amount  of  storage 
space.  For  instance,  a  bitmap  representation  of  an  entire  640-by-480-pixel,  16-color  VGA 
screen  requires  over  150  KB.  Metafiles  usually  require  much  less  storage  space  than  bit¬ 
maps.  The  storage  space  for  a  bitmap  is  governed  by  the  size  of  the  image  and  number  of 
colors  it  contains,  whereas  the  storage  space  for  a  metafile  is  governed  by  the  complexity  of 
the  image  and  the  number  of  individual  GDI  instructions  it  contains. 

One  advantage  of  bitmaps  over  metafiles,  however,  is  speed.  Copying  a  bitmap  to  a 
video  display  is  usually  much  faster  than  rendering  a  metafile. 

In  the  introduction  to  GDI  in  Chapter  11, 1  talked  about  two  types  of  device  contexts 
that  don’t  refer  to  real  devices:  the  memory  device  context  and  the  metafile  device  context. 
We’ll  see  how  these  work  as  we  examine  bitmaps  and  metafiles  and  explore  the  ways  we 
can  create,  use,  and  manipulate  them.  The  subject  of  bitmaps  and  metafiles  will  come  up 
again  in  Chapter  16,  “The  Clipboard.”  Text,  bitmaps,  and  metafiles  are  the  three  primary 
forms  of  data  that  can  be  shared  by  applications  through  the  clipboard. 

COLOR  AND  BITMAPS 

Each  pixel  in  an  image  corresponds  to  one  or  more  bits  in  a  bitmap.  A  monochrome  image 
requires  1  bit  per  pixel.  A  color  image  requires  more  than  1  bit  per  pixel.  The  number  of  dif¬ 
ferent  colors  that  can  be  represented  by  a  bitmap  is  equal  to  2  to  the  power  of  the  number 
of  bits  per  pixel.  For  example,  a  16-color  bitmap  requires  4  bits  per  pixel,  and  a  256-color 
bitmap  requires  8  bits  per  pixel. 

Prior  to  Windows  3.0,  the  only  bitmaps  supported  under  Windows  were  GDI  objects, 
which  were  referenced  using  a  bitmap  handle.  These  bitmaps  were  either  monochrome  or 
had  the  same  color  organization  as  a  real  graphics  output  device,  such  as  a  video  display. 
For  example,  a  bitmap  compatible  with  a  VGA  had  four  color  planes. 

The  problem  was  that  these  color  bitmaps  could  not  be  saved  and  used  on  a  graphics 
output  device  with  a  different  color  organization — say,  an  IBM  8514/A,  capable  of  dis¬ 
playing  256  colors  and  using  8  bits  per  pixel. 

For  Windows  3.0,  a  new  bitmap  format  was  defined,  called  the  device-independent 
bitmap,  or  DIB.  The  DIB  included  its  own  color  table  that  showed  how  the  pixel  bits  corre¬ 
spond  to  RGB  colors.  DIBs  can  be  displayed  on  any  raster  output  device.  The  only 
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problem  is  that  the  colors  of  the  DIB  must  be  converted  to  the  nearest  colors  that  the  device 
can  actually  render. 


THE  DEVICE-INDEPENDENT  BITMAP  (DIB) 

When  I  demonstrated  the  use  of  bitmaps  in  previous  chapters,  I  created  GDI  bitmap  ob¬ 
jects  using  functions  such  as  CreateBitmap  and  LoadBitmap.  These  functions  return  a 
handle  to  a  bitmap  of  type  HBITMAP.  The  actual  bitmaps  reside  in  memory  controlled  by 
GDI.  These  GDI  bitmap  objects  have  been  supported  in  Windows  since  Windows  1.0. 
They  must  be  either  monochrome  bitmaps  or  color  bitmaps  that  are  compatible  with  the 
video  display  or  with  a  printer. 

The  DIB  format  is  called  “device  independent”  because  it  contains  a  color  table.  The 
color  table  describes  how  the  pixel  values  correspond  to  RGB  color  values.  This  color  table 
may  not  necessarily  be  compatible  with  a  particular  graphics  output  device. 

The  DIB  format  is  an  extension  of  the  bitmap  format  supported  in  the  OS/2  1.1  Pre¬ 
sentation  Manager.  The  WINDOWS.H  header  file  contains  some  structures  for  working 
with  OS/2  bitmaps.  The  OS/2  2.0  Presentation  Manager  supports  bitmaps  that  are  an  exten¬ 
sion  of  the  DIB. 

With  the  introduction  of  the  DIB,  the  GDI  bitmap  objects  are  sometimes  called  “de¬ 
vice-dependent  bitmaps.”  They  are  device  dependent  because  they  must  be  compatible 
with  a  specific  graphics  output  device.  The  DIB  is  not  a  GDI  object.  GDI  cannot  store  DIBs. 
DIBs  must  be  stored  outside  GDI  in  files  or  global  memory  blocks.  Once  GDI  gets  hold  of  a 
DIB,  it  turns  it  into  a  device-dependent  bitmap,  compatible  with  some  real  output  device. 

DIBs  are  primarily  for  interchange  among  programs.  They  can  be  passed  among  pro¬ 
grams  either  by  storing  them  in  files  or  copying  them  to  the  clipboard. 

A  DIB  can  be  converted  to  a  device-dependent  GDI  bitmap  object;  in  such  a  case,  the 
device-independent  color  information  in  the  DIB  is  lost.  A  GDI  bitmap  object  can  also  be 
used  to  construct  a  DIB,  in  which  case  the  DIB  will  contain  a  color  table  compatible  with 
the  graphics  output  device  with  which  the  GDI  bitmap  object  is  compatible. 

If  you  need  to  store  bitmap  information  in  a  file  or  to  read  bitmap  files  or  to  pass  bit¬ 
map  information  into  and  out  of  the  clipboard  in  a  device-independent  format,  you  should 
use  DIBs.  However,  if  you  only  need  to  create  or  use  monochrome  bitmaps,  or  if  you  only 
need  bitmaps  within  your  own  program  that  are  compatible  with  the  video  display,  then 
using  device-dependent  GDI  bitmap  objects  is  usually  easier. 

The  DIB  File 

You  can  create  a  device-independent  bitmap  and  save  it  on  a  disk  file  in  the  Microsoft  Im¬ 
age  Editor  or  in  the  Borland  Resource  Workshop  or  in  the  PAINTBRUSH  program  included 
in  the  retail  Windows  product.  The  files  generally  have  the  extension  .BMP,  although  some 
DIBs  can  be  found  with  the  extension  .DIB. 
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The  DIB  file  begins  with  a  file  header  section  defined  by  the  BITMAPFILEHEADER 
structure.  This  structure  has  five  fields: 


Field 

Size 

Description 

bfType 

UINT 

The  bytes  “BM”  (for  bitmap) 

bfSize 

DWORD 

Total  size  of  the  file 

bfReservedl 

UINT 

Set  to  0 

bfReserved2 

UINT 

Set  to  0 

bf OffBits 

DWORD 

Offset  to  the  bitmap  bits  from  the  beginning  of  the  file 

This  is  followed  by  another  header  defined  by  the  BITMAPINFOHEADER  structure. 
This  structure  has  11  fields: 


Field 

Size 

Description 

biSize 

DWORD 

Size  of  this  structure  in  bytes 

biWidth 

LONG 

Width  of  the  bitmap  in  pixels 

biHeight 

LONG 

Height  of  the  bitmap  in  pixels 

biPlanes 

WORD 

Set  to  1 

biBitCount 

WORD 

Color  bits  per  pixel  (1,  4,  8,  or  24) 

biCompression 

DWORD 

Compression  scheme  (0  for  none) 

biSizelmage 

DWORD 

Size  of  bitmap  bits  in  bytes  (only  required  if 
compression  is  used) 

b  iXPelsPerMeter 

LONG 

Horizontal  resolution  in  pixels  per  meter 

bi  YPelsPerMeter 

LONG 

Vertical  resolution  in  pixels  per  meter 

biClrUsed 

DWORD 

Number  of  colors  used  in  image 

biClrlmportant 

DWORD 

Number  of  important  colors  in  image 

All  fields  following  the  biBitCount  field  may  be  set  to  0  for  default  values  (or  may  not  even 
appear  in  the  file).  Thus,  the  structure  can  be  as  small  as  16  bytes  in  length.  It  can  also  con¬ 
tain  additional  fields  beyond  those  shown  here. 

If  biClrUsed  is  set  to  0  and  the  number  of  color  bits  per  pixel  is  1,  4,  or  8,  the  BIT¬ 
MAPINFOHEADER  structure  is  followed  by  a  color  table,  which  consists  of  two  or  more 
RGBQUAD  structures.  The  RGBQUAD  structure  defines  an  RGB  color  value: 


Field 

Size 

Description 

rgbBlue 

BYTE 

Blue  intensity 

rgbGreen 

BYTE 

Green  intensity 

rgbRed 

BYTE 

Red  intensity 

rgbReserved 

BYTE 

Set  to  0 
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The  number  of  RGBQUAD  structures  is  usually  determined  by  the  biBitCount field:  2 
RGBQUAD  structures  are  required  for  1  color  bit,  16  for  4  color  bits,  and  256  for  8  color  bits. 
However,  if  the  biClrUsed  field  is  nonzero,  then  the  biClrUsed  field  contains  the  number  of 
RGBQUAD  structures  in  the  color  table. 

The  color  table  is  followed  by  the  array  of  bits  that  define  the  bitmap  image.  This  ar¬ 
ray  begins  with  the  bottom  row  of  pixels.  Each  row  begins  with  the  leftmost  pixels.  Each 
pixel  corresponds  to  1,  4,  8,  or  24  bits. 

For  a  monochrome  bitmap  with  1  color  bit  per  pixel,  the  first  pixel  in  each  row  is  rep¬ 
resented  by  the  most  significant  bit  of  the  first  byte  in  each  row.  If  this  bit  is  0,  the  color  of 
the  pixel  can  be  obtained  from  the  first  RGBQUAD  structure  in  the  color  table.  If  the  bit  is 
1,  the  color  is  given  by  the  second  RGBQUAD  structure  in  the  color  table. 

For  a  16-color  bitmap  with  4  color  bits  per  pixel,  the  first  pixel  in  each  row  is  repre¬ 
sented  by  the  most  significant  four  bits  of  the  first  byte  in  each  row.  The  color  of  each  pixel 
is  obtained  by  using  the  4-bit  value  as  an  index  into  the  16  entries  in  the  color  table. 

For  a  256-color  bitmap,  each  byte  corresponds  to  one  pixel.  The  color  of  the  pixel  is 
obtained  by  using  the  8-bit  value  as  an  index  into  the  256  entries  in  the  color  table. 

If  the  bitmap  image  contains  24  color  bits  per  pixel,  each  set  of  three  bytes  is  an  RGB 
value  of  the  pixel.  There  is  no  color  table  (unless  the  biClrUsed  field  in  the  BITMAP- 
INFOHEADER  structure  is  nonzero). 

In  each  case,  each  row  of  the  bitmap  data  contains  a  multiple  of  4  bytes.  The  row  is 
padded  to  the  right  to  ensure  this. 

The  bitmap  format  supported  in  OS/2  1.1  and  later  is  very  similar.  It  begins  with  a 
BITMAPFILEHEADER  structure  but  is  followed  by  a  12-byte  BITMAPCOREHEADER 
structure.  (You  can  determine  whether  a  bitmap  file  uses  this  format  or  the  Windows  for¬ 
mat  by  examining  the  first  field  of  this  structure.)  The  color  table  consists  of  RGBTRIPLE 
structures  rather  than  RGBQUAD  structures. 

The  Packed-DIB  Memory  Format 

If  you  encounter  a  DIB  file  that  you’d  like  to  read  into  a  Windows  program,  you  can  read  it 
directly  into  a  global  memory  block.  (Very  often  these  memory  blocks  will  be  greater  than 
64  KB  in  length.)  This  is  known  as  the  “packed-DIB  memory  format.”  It  consists  of  every¬ 
thing  in  the  DIB  file  except  the  BITMAPFILEHEADER  structure. 

Thus,  a  global  memory  block  containing  a  DIB  begins  with  a  BITMAPINFOHEADER 
structure,  followed  by  a  color  table  (if  one  is  present),  followed  by  the  bitmap  bits  them¬ 
selves.  The  packed-DIB  memory  format  is  used  for  copying  DIBs  to  and  from  the 
clipboard. 

You  can  also  use  the  packed-DIB  memory  format  to  display  the  bitmap  on  the  screen 
using  the  SetDIBitsToDevice  or  StretchDIBits  function,  to  create  a  brush  based  on  a  DIB 
( CreateDIBPatternBrush ),  or  to  create  a  device- dependent  GDI  bitmap  object  from 
a  DIB  (CreateDl Bitmap). 
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In  any  case,  you  must  calculate  the  address  within  the  global  memory  block  where 
the  bitmaps  bits  begin.  You  can  do  this  by  examining  the  BITMAPINFOHEADER  structure 
and  determining  the  size  of  the  color  table.  This  process  is  shown  in  the  SHOWDIB  pro¬ 
gram  in  the  next  section. 

Displaying  a  DIB 

Windows  has  two  functions  to  display  a  DIB  from  a  packed-DIB  memory  block.  The  most 
general  is  StretchDIBits,  which  allows  the  bitmap  to  be  stretched  or  compressed  and  which 
can  use  various  raster  operations  discussed  later  in  this  chapter.  The  SetDIBitsToDevice 
function  is  somewhat  simpler;  it  displays  the  bitmap  without  stretching  or  compressing, 
and  it  cannot  use  any  raster  operations. 

These  two  functions — as  well  as  the  process  of  reading  a  DIB  from  a  file  into  a  global 
memory  block — are  demonstrated  in  the  SHOWDIB  program  in  Figure  13-1. 

SHOWDIB.MAK 


//---- . 

//  SHOWDIB.MAK  make  file 

// . 


showdib.exe  :  showdib.obj  showdib.def  showdib.res 

$ ( WINLINK)  showdib,  showdib,  NUL,  $(WINLIB),  showdib 
rc  -t  showdib.res 

showdib.obj  :  showdib. c  showdib. h 
$(WINCC)  showdib. c 

showdib.res  :  showdib. rc  showdib. h 
$(WINRC)  showdib. rc 


SHOWDIB.C 


/* .  .  .  - 

SHOWDIB.C  --  Show  DIB  in  Window 

(c)  Charles  Petzold,  1992 
.  .  */ 


//include  <windows.h> 
//include  <windowsx.h> 
//include  <commdlg-h> 


Figure  13-1 .  The  SHOWDIB  program  . 


(continued) 
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//include  <stdlib.h> 

//include  "showdib.h" 

//define  MIN(a.b)  ((a)  <  (b)  ?  (a)  :  (b)) 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 
char  szAppName  []  =  "ShowDib"  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass. hbrBackground 
wndclass. IpszMenuName 
wndclass.lpszClassName 


=  CS.HREDRAW  !  CS.VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL,  IDC.ARROW)  ; 
=  GetStockObject  (WHITE.BRUSH)  ; 
=  szAppName  ; 

=  szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "Show  DIB  in  Window", 
WS.OVERLAPP EDWIN DOW , 
CW.USEDEFAULT,  CW.USEDEFAULT, 
CW.USEDEFAULT,  CW.USEDEFAULT, 
NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 
{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


(continued) 
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//  Functions  for  extracting  information  from  DIB  memory  blocks 

DWORD  GetDi blnfoHeaderSi ze  (BYTE  huge  *  lpDib) 

{ 

return  ( (BITMAPINFOHEADER  huge  *)  1 pDi b ) - >bi Si ze  ; 

} 

WORD  GetDi bWi dth  (BYTE  huge  *  lpDib) 

{ 

if  (GetDi blnfoHeaderSi ze  (lpDib)  ==  sizeof  ( BITMAPCOREHEADER) ) 
return  (WORD)  (((BITMAPCOREHEADER  huge  *)  1 pDi b ) - >bcWi dth )  ; 

else 

return  (WORD)  (((BITMAPINFOHEADER  huge  *)  1 pDi b ) - >bi Wi dth )  ; 


WORD  GetDibHeight  (BYTE  huge  *  lpDib) 

{ 

if  (GetDi blnfoHeaderSi ze  (lpDib)  ==  sizeof  (BITMAPCOREHEADER)) 

return  (WORD)  (((BITMAPCOREHEADER  huge  *)  1 pDi b ) - >bcHei ght )  ; 

else 

return  (WORD)  (((BITMAPINFOHEADER  huge  *)  1 pDi b ) - >bi Hei ght )  ; 


BYTE  huge  *  GetDi bBi tsAdd r  (BYTE  huge  *  lpDib) 

{ 

DWORD  dwNumColors,  dwCol orTableSize  ; 

WORD  wBitCount  ; 

if  (GetDi blnfoHeaderSi ze  (lpDib)  ==  sizeof  (BITMAPCOREHEADER)) 

{ 

wBitCount  =  ((BITMAPCOREHEADER  huge  *)  1 pDi b) ->bcBi tCount  ; 

if  (wBitCount  !=  24) 

dwNumColors  =  1L  <<  wBitCount  ; 

else 

dwNumColors  =  0  ; 

dwColorTableSize  =  dwNumColors  *  sizeof  (RGBTRIPLE)  ; 

} 

else 

{ 

wBitCount  =  ((BITMAPINFOHEADER  huge  *)  lpDib)->biBitCount  ; 

if  (GetDiblnfoHeaderSize  (lpDib)  >=  36) 

dwNumColors  =  ((BITMAPINFOHEADER  huge  *)  lpDib)->biCl rUsed  ; 

else 

dwNumColors  =  0  ; 

if  (dwNumColors  ==  0) 

{ 
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if  (wBitCount  !=  24) 

dwNumColors  =  1L  «  wBitCount  ; 

else 

dwNumColors  =  0  ; 

} 

dwColorTableSize  =  dwNumColors  *  sizeof  (RGBQUAD)  ; 

} 

return  lpDib  +  GetDiblnfoHeaderSize  (lpDib)  +  dwColorTableSize  ; 
} 


//  Read  a  DIB  from  a  file  into  memory 

BYTE  huge  *  ReadDib  (char  *  szFileName) 

{ 

BITMAPFILEHEADER  bmfh  ; 

BYTE  huge  *  lpDib  ; 

DWORD  dwDibSize,  dwOffset,  dwHeaderSize  ; 

int  hFile  ; 

WORD  wDibRead  ; 

if  (-1  ==  (hFile  =  _lopen  (szFileName,  OF.READ  !  OF_SHAREJENY_WRITE) ) ) 

return  NULL  ; 

if  (_1  read  (hFile,  (LPSTR)  &bmfh,  sizeof  (BITMAPFILEHEADER))  !  = 

sizeof  (BITMAPFILEHEADER)) 

{ 

Jclose  (hFile)  ; 
return  NULL  ; 

} 

if  (bmfh.bfType  !=  *  (WORD  *)  "BM") 

{ 

Jclose  (hFile)  ; 
return  NULL  ; 

} 

dwDibSize  =  bmfh.bfSize  -  sizeof  (BITMAPFILEHEADER)  ; 

lpDib  =  (BYTE  huge  *  )  GlobalAllocPtr  (GMEM.MOVEABLE,  dwDibSize)  ; 

if  (lpDib  ==  NULL) 

{ 

Jclose  (hFile)  ; 
return  NULL  ; 

} 

dwOffset  =  0  ; 
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/ 


while  (dwDibSize  >  0) 

{ 

wDibRead  =  (WORD)  MIN  (32768ulf  dwDibSize)  ; 

if  (wDibRead  i=  _1 read  (hFile,  (LPSTR)  (lpDib  +  dwOffset),  wDibRead)) 

{ 

_lc1ose  (hFile)  ; 

GlobalFreePtr  (lpDib)  ; 
return  NULL  ; 

} 

dwDibSize  -=  wDibRead  ; 
dwOffset  +=  wDibRead  ; 

} 

Jlclose  (hFile)  ; 

dwHeaderSize  =  GetDiblnfoHeaderSize  (lpDib)  ; 

if  (dwHeaderSize  <  12  ! !  (dwHeaderSize  >  12  &&  dwHeaderSize  <  16)) 

{ 

GlobalFreePtr  (lpDib)  ; 
return  NULL  ; 

} 

return  lpDib  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


{ 

static  char 
static  char  * 


static  BYTE  huge  * 

static  OPENFILENAME 

static  short 

static  WORD 

HDC 

HMENU 

BYTE  huge  * 
PAINTSTRUCT 
short 


szFileName  [_MAX_PATH] . 
szTitleName  [_MAX_FNAME  +  _MAX_EXT]  ; 
szFi 1  ter [ ]  =  {  "Bitmap  Files  (*.BMP)", 
"DIB  Files  (*.DIB)"f 

j  . 

lpDib  ; 
ofn  ; 

cxClient,  cyClient  ; 

wDi splay  =  IDMJ\CTUAL  ; 

hdc  ; 

hMenu  ; 

lpDibBits  ; 

ps  ; 

cxDib,  cyDib  ; 


"*.bmp", 

"*.dib", 


switch  (message) 

{ 

case  WM.CREATE  : 

ofn.lStructSize  =  sizeof  (OPENFILENAME)  ; 
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ofn.hwndOwner 

ofn.lpstrFilter 

ofn.lpstrFile 

ofn.nMaxFile 

ofn.lpstrFileTitle 

ofn.nMaxFileTitle 

ofn.lpstrDefExt 

return  0  ; 


=  hwnd  ; 

=  szFilter  [0]  ; 

=  szFileName  ; 

=  _MAX_PATH  ; 

=  szTitleName  ; 

=  _MAX_FNAME  +  _MAX_EXT  ; 
=  "bmp"  ; 


case  WM_SIZE  : 

cxClient  =  LOWORD  ( 1 Param)  ; 
cyClient  =  HIWORD  Cl  Param)  ; 
return  0  ; 


case  WM.COMMAND  : 

hMenu  =  GetMenu  (hwnd)  ; 


switch  (wParam) 

{ 

case  IDM_0PEN  : 

if  (GetOpenFileName  (&ofn)) 

{ 

if  (lpDib  !=  NULL) 

{ 

Global FreePtr  (lpDib)  ; 
lpDib  =  NULL  ; 

} 


lpDib  =  ReadDib  (szFileName)  ; 

if  (lpDib  ==  NULL) 

MessageBox  (hwnd,  szAppName, 

"Could  not  open  DIB  file", 
MB_I CONEXCLAMATI ON  !  MB_0K)  ; 


InvalidateRect  (hwnd,  NULL.  TRUE)  ; 
} 

return  0  ; 


case  IDM.ACTUAL  : 
case  I DM__STRETCH  : 

CheckMenuItem  (hMenu,  wDisplay,  MF_UNCHECKED)  ; 
wDisplay  =  wParam  ; 

CheckMenuItem  (hMenu,  wDisplay,  MF_CHECKED)  ; 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

} 

break  ; 
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case  WM_PAINT  : 

hdc  =  BeginPaint  (hwnd.  &ps)  ; 

if  (lpDib  !=  NULL) 

{ 

lpDibBits  =  GetDi bBi tsAddr  (lpDib)  ; 
cxDib  =  GetDibWidth  (lpDib)  ; 
cyDib  =  GetDi bHeight  (lpDib)  ; 

SetStretchBl tMode  (hdc.  C0L0R0NC0L0R)  ; 


if  (wDi splay  ==  IDM.ACTUAL) 

SetDIBitsToDevice  (hdc.  0,  0.  cxDib,  cyDib.  0.  0. 

0.  cyDib.  (LPSTR)  lpDibBits. 
(LPBITMAPINFO)  lpDib. 
DIB_RGB_C0L0RS)  ; 


else 

StretchDIBits  (hdc.  0,  0.  cxClient,  cyClient. 
0,  0.  cxDib,  cyDib, 

(LPSTR)  lpDibBits. 
(.LPBITMAPINFO)  lpDib, 
DIB_RGB_C0L0RS,  SRCCOPY)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

if  (lpDib  !=  NULL) 

Global FreePtr  (lpDib)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParan)  ; 

} 


SHOWDIB.RC 

/* . . . 

SHOWDIB.RC  resource  script 
. - . ---*/ 

#include  "showdib.h" 

ShowDib  MENU 
{ 
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POPUP  "&File" 

{ 

MENUITEM  "&0pen. . IDM_0PEN 

} 

POPUP  "&Di splay" 

{ 

MENUITEM  "&Actual  Size",  IDM_ACTUAL,  CHECKED 

MENUITEM  "&Stretch  to  Window" f  IDM_STRETCH 

} 

} 


SHOWDIB.H 


/* . - . . 

SHOWDIB.H  header  file 
. */ 


♦define  IDM_0PEN  10 
♦define  IDM.ACTUAL  20 
♦define  IDM.STRETCH  21 


SHOWDIB.DEF 


SHOWDIB.DEF  module  definition  file 


NAME 


SHOWDIB 


DESCRIPTION  'Show  DIB  in  Window  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


When  you  select  Open  from  the  File  menu,  SHOWDIB  displays  the  File  Open  dialog 
box  from  the  common  dialog  box  library  (discussed  in  Chapter  10).  It  then  calls  the  func¬ 
tion  ReadDib. 

The  ReadDib  function  reads  a  DIB  file  into  a  global  memory  block,  allocated  using 
the  macro  GlobalAllocPtr  defined  in  WINDOWSX.H.  After  opening  the  file,  the  function 
reads  the  beginning  of  the  file  into  a  BITMAPFILEHEADER  structure.  The  first  two  bytes 
(the  bfType  field)  are  checked  for  the  “BM”  signature,  and  then  the  bfSize  field  is 
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used  to  calculate  the  size  of  the  file  less  the  size  of  the  BITMAPFILEHEADER  structure. 
The  result  is  the  size  of  the  packed-DIB  memory  block. 

ReadDib  then  allocates  a  global  memory  block  of  that  size.  Notice  that  the  variable 
used  to  store  the  pointer  to  this  memory  block  is  defined  as  a  “huge”  pointer.  (Many  DIBs 
are  greater  than  64  KB  in  length,  and  you  must  use  huge  pointers  so  that  the  compiler  gen¬ 
erates  proper  code  for  progression  through  the  multiple  segments  of  the  DIB.)  At  that 
point,  the  remainder  of  the  file  is  simply  read  into  the  memory  block  in  32-KB  chunks. 

Finally,  there  is  one  last  verification  check:  ReadDib  calls  GetDiblnfoHeaderSize 
(which  simply  extracts  the  first  DWORD  from  the  memory  block)  and  checks  whether 
it’s  12  bytes  long  (in  which  case  the  program  is  dealing  with  an  OS/2  1.x  bitmap  file)  or  at 
least  16  bytes  long  (in  which  case  it’s  a  Windows  DIB). 

The  GetDibWidth  and  GetDibHeight  functions  in  SHOWDIB  extract  the  bitmap 
width  and  height  from  the  memory  block.  The  GetDibBitsAddr function  is  more  complex. 
It  requires  some  information  in  the  BITMAPINFOHEADER  structure  to  calculate  the 
address  of  the  bitmap  bits  within  the  DIB. 

These  three  functions  are  used  during  the  WM_PAINT  message  in  WndProc  to  pass 
parameters  to  the  SetDIBitsToDevice  or  StretchDIBits  functions.  Both  functions  require  a 
pointer  to  a  BITMAPINFOHEADER  structure — the  beginning  of  the  DIB  memory  block — 
and  a  pointer  to  the  bitmap  bits.  The  StretchDIBits  function  is  particularly  versatile — 
allowing  you  to  display  any  rectangle  within  the  bitmap  at  a  specified  logical  width  and 
height  on  the  display. 

Creating  a  DIB 

If  you  have  a  16-color  or  256-color  video  display  and  read  in  a  full-color  bitmap  with  24  bits 
per  pixel,  you’ll  notice  that  the  bitmap  requires  some  time  to  be  displayed.  This  is  because 
the  device  driver  must  perform  a  nearest-color  search  for  each  of  the  pixels  in  the  bitmap. 

You  can  speed  up  the  display  process  by  converting  the  DIB  to  a  device-dependent 
GDI  bitmap  object  using  the  CreateDI Bitmap  function.  The  nearest-color  search  would 
have  to  be  performed  only  once,  and  then  the  bitmap  object  would  be  in  the  same  format 
as  the  video  display.  Using  the  variables  in  SHOWDIB,  the  function  call  would  be: 

hBitmap  =  CreateDIBi tmap  (hdc, 

( LPB I TMAP I NFOHEADER)  lpDib. 

CBM.INIT.  ( LPSTR)  IpDibBits, 

( LPB I TMAP  I N  FO )  lpDib, 

DIB_RGB_C0L0RS)  ; 

Contrary  to  the  name  of  this  function,  CreateDI  Bitmap  does  not  create  a  DIB.  It 
creates  a  device-dependent  GDI  bitmap  object  from  a  DIB  specification,  and  it  returns  a 
handle  to  the  object.  This  GDI  bitmap  object  is  compatible  with  the  graphics  output  device 
whose  handle  is  passed  as  the  first  parameter.  As  when  displaying  a  DIB,  GDI  must  convert 
the  device-independent  colors  to  the  colors  of  the  device. 
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Following  this  call,  you  can  display  the  bitmap  by  selecting  the  bitmap  handle  into  a 
memory  device  context  and  using  BitBlt ,  as  shown  later  in  this  chapter. 

You  can  also  use  the  CreateDI Bitmap  to  create  an  uninitialized  GDI  bitmap  object: 

hBitmap  =  CreateDIBitmap  (hdc,  &bmi h ,  0L,  NULL,  NULL,  0)  ; 

Two  functions  are  available  to  set  and  obtain  the  bits  of  the  bitmap.  The  first  function 
sets  the  bits: 

SetDIBits  (hdc,  hBitmap,  nStart,  nNum,  lpBits,  &bmi ,  wUsage)  ; 

The  last  three  parameters  are  the  same  as  those  in  the  CreateDIBitmap  function.  The 
nStart  parameter  indicates  the  beginning  scan  line  addressed  by  lpBits.  This  can  range 
from  0  (for  the  bottom  scan  line)  to  the  height  of  the  bitmap  in  pixels  minus  1  (for  the  top 
scan  line).  The  nNum  parameter  indicates  the  number  of  scan  lines  to  set  into  the  bitmap. 
The  GetDIBits  function  has  identical  parameters: 

GetDIBits  (hdc,  hBitmap,  nStart,  nNum,  lpBits,  &bmi ,  wUsage)  ; 

But  in  this  case,  lpBits  points  to  a  buffer  to  receive  the  bitmap  bits.  The  function  sets  the 
fields  of  the  BITMAPINFO  structure  to  indicate  the  dimensions  of  the  bitmap  and  the  color 
table. 


THE  GDI  BITMAP  OBJECT 

The  old  bitmap  format  that  originated  in  Windows  1  is  very  limited  and  highly  dependent 
on  the  output  device  for  which  the  bitmap  is  created.  You  should  use  the  DIB  format  rather 
than  the  old  bitmap  format  for  storing  bitmap  files  on  disk.  However,  when  you  need  a  bit¬ 
map  solely  for  use  within  a  program,  working  with  device-dependent  bitmaps  is  much 
easier  and  gives  better  performance. 


Creating  Bitmaps  in  a  Program 

Windows  includes  five  functions  that  let  you  create  a  device-dependent  GDI  bitmap  object 
in  your  program.  The  first  is  the  CreateDIBitmap  function  discussed  above.  The  others 
are: 


hBitmap  =  CreateBitmap  (cxWidth,  cyHeight,  nPlanes,  nBitsPixel,  lpBits)  ; 

hBitmap  =  CreateBitmapIndi rect  Ubitmap)  ; 

hBitmap  =  CreateCompatibleBitmap  (hdc,  cxWidth,  cyHeight)  ; 

hBitmap  =  CreateDi scardabl eBitmap  (hdc,  cxWidth,  cyHeight)  ; 

The  CreateDiscardableBitmap  function  is  rarely  used  and  is  not  recommended. 

In  all  cases,  the  cxWidth  and  cyHeight  parameters  are  the  width  and  the  height  of  the 
bitmap  in  pixels.  In  CreateBitmap ,  the  nPlanes  and  nBitsPixel  parameters  are  the  number 
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of  color  planes  and  the  number  of  color  bits  per  pixel  in  the  bitmap.  At  least  one  of  these 
parameters  should  be  set  to  1.  If  both  parameters  are  1,  the  function  creates  a  monochrome 
bitmap.  (I’ll  discuss  how  the  color  planes  and  color  bits  represent  color  shortly.) 

In  the  CreateBitmap  function,  IpBits  can  be  set  to  NULL  if  you  are  creating  an 
uninitialized  bitmap.  The  resultant  bitmap  contains  random  data.  In  the  CreateCompat- 
ibleBitmap  and  CreateDiscardableBitmap  functions,  Windows  uses  the  device  context  ref¬ 
erenced  by  hdcio  obtain  the  number  of  color  planes  and  the  number  of  color  bits  per  pixel. 
The  bitmap  created  by  these  functions  is  uninitialized. 

CreateBitmapIndirect  is  similar  to  CreateBitmap  except  that  it  uses  the  bitmap  struc¬ 
ture  of  type  BITMAP  to  define  the  bitmap.  The  following  table  shows  the  fields  of  this 
structure: 


Field 

Type 

Description 

bmType 

int 

Set  to  0 

bmWidth 

int 

Width  of  bitmap  in  pixels 

bmHeight 

int 

Height  of  bitmap  in  scan  lines 

bmWidthBytes 

int 

Width  of  bitmap  in  bytes  (must  be  even) 

bmP lanes 

BYTE 

Number  of  color  planes 

bmBitsPixel 

BYTE 

Number  of  color  bits  per  pixel 

bmBits 

void  FAR  * 

Far  pointer  to  array  of  bits 

The  bmWidth Bytes  field  must  be  an  even  number — the  lowest  even  number  of  bytes 
required  to  store  one  scan  line.  The  array  of  the  bits  referenced  by  bmBits  must  be 
organized  based  on  the  bmWidthBytes  field.  If  bm  is  a  structure  variable  of  type  BITMAP, 
you  can  calculate  the  bmWidthBytes  field  by  using  the  following  statement: 

bm. bmWidthBytes  =  (bm. bmWidth  *  bm.bmBitsPixel  +  15)  /  16  *  2  ; 

If  Windows  cannot  create  the  bitmap  (generally  because  not  enough  memory  is  available), 
it  will  return  a  NULL.  You  should  check  the  return  values  from  the  bitmap  creation  func¬ 
tions,  particularly  if  you’re  creating  large  bitmaps. 

The  handle  to  the  bitmap  is  not  a  handle  to  a  global  memory  block,  so  don’t  try  to  use 
the  GlobalLock function  on  it.  The  handle  is  instead  a  local  handle  to  the  GDI  module’s  data 
segment.  This  handle  references  a  small  local  memory  block  in  GDI  that  contains  a  second 
handle  to  a  global  memory  block  containing  the  information  in  the  BITMAP  structure  and 
the  actual  bits. 

Once  you  create  a  bitmap,  you  cannot  change  the  size,  the  number  of  color  planes,  or 
the  number  of  color  bits  per  pixel.  You  would  have  to  create  a  new  bitmap  and  transfer  the 
bits  from  the  original  bitmap  to  this  new  bitmap.  If  you  have  a  handle  to  a  bitmap,  you  can 
get  the  size  and  color  organization  using: 

GetObject  (hBitmap,  sizeof  (BITMAP),  ( LPSTR)  &bitmap)  ; 


620 


Chapter  13:  Bits,  Bits,  and  Metafiles 


This  copies  the  information  about  the  bitmap  into  a  structure  (called  bitmap  here)  of  type 
BITMAP.  This  function  doesn’t  fill  in  the  bmBits  field.  To  get  access  to  the  actual  bits  of  the 
bitmap,  you  must  call: 

GetBi tmapBi ts  (hBitmap,  dwCount,  lpBits)  ; 

This  copies  dwCount  bits  into  a  character  array  referenced  by  the  far  pointer  lpBits.  To  en¬ 
sure  that  all  the  bits  of  the  bitmap  are  copied  into  this  array,  you  can  calculate  the  dwCount 
parameter  based  on  the  fields  of  the  bitmap  structure: 

dwCount  =  (DWORD)  bitmap. bmWidthBytes  *  bitmap. bmHeight  *  bitmap. bmPl anes  ; 

You  can  also  direct  Windows  to  copy  a  character  array  containing  the  bitmap  bits  back  into 
an  existing  bitmap  using  the  function: 

SetBi tmapBi ts  (hBitmap,  dwCount,  lpBits)  ; 

Because  bitmaps  are  GDI  objects,  you  should  delete  any  bitmap  you  create: 

DeleteObject  (hBitmap)  ; 

The  Monochrome  Bitmap  Format 

For  a  monochrome  bitmap,  the  format  of  the  bits  is  relatively  simple  and  can  almost  be 
derived  directly  from  the  image  you  want  to  create.  For  instance,  suppose  you  want  to 
create  a  bitmap  that  looks  like  this: 


You  can  write  down  a  series  of  bits  (0  for  black  and  1  for  white)  that  directly  corre¬ 
sponds  to  this  grid.  Reading  these  bits  from  left  to  right,  you  can  then  assign  each  group  of 
8  bits  a  hexadecimal  byte.  If  the  width  of  the  bitmap  is  not  a  multiple  of  16,  pad  the  bytes  to 
the  right  with  zeros  to  get  an  even  number  of  bytes: 

0  1  0  1  0  0  0  1  0  1  1  1  0  1  1  1  0  0  0  1  =  51  77  10  00 

0  1  0  1  0  1  1  1  0  1  1  1  0  1  1  1  0  1  0  1  =  57  77  50  00 

0  0  0  1  0  0  1  1  0  1  1  1  0  1  1  1  0  1  0  1  =  13  77  50  00 

0  1  0  1  0  1  1  1  0  1  1  1  0  1  1  1  0  1  0  1  =  57  77  50  00 

0  1  0  1  0  0  0  1  0  0  0  1  0  0  0  1  0  0  0  1  =  51  11  10  00 

The  width  in  pixels  is  20,  the  height  in  scan  lines  is  5,  and  the  width  in  bytes  is  4.  You 
can  set  up  a  BITMAP  structure  for  this  bitmap  with  the  following  statement: 

static  BITMAP  bitmap  =  {  0,  20,  5,  4,  1,  1  }  ; 


621 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


and  you  can  store  the  bits  in  a  BYTE  array: 


static  BYTE 


byBits  []  =  {  0x51,  0x77, 
0x57,  0x77, 
0x13,  0x77, 
0x57,  0x77, 
0x51,  0x11, 


0x10, 

0x50, 

0x50, 

0x50, 

0x10, 


0x00 , 
0x00 , 
0x00, 
0x00, 
0x00  }  ; 


Creating  the  bitmap  with  CreateBitmapIndirect  requires  two  statements: 
bitmap. bmBits  =  (LPSTR)  byBits  ; 


hBitmap  =  CreateBitmapIndirect  ( &bi tmap )  ; 

Be  careful  when  working  with  the  pointer  to  byBits.  It’s  OK  to  call  CreateBitmapIndirect 
immediately  after  you  assign  the  far  address  to  the  bmBits  field,  but  in  real  mode  this  field 
can  become  invalid  if  Windows  moves  your  local  data  segment. 

You  may  prefer  the  following  statements,  which  avoid  this  problem: 

hBitmap  =  CreateBitmapIndirect  (&bitmap)  ; 


SetBitmapBits  (hBitmap,  (DWORD)  sizeof  byBits,  byBits)  ; 

You  can  also  avoid  using  the  bitmap  structure  entirely  and  create  the  bitmap  in  one 
statement: 

hBitmap  =  CreateBitmap  (20,  5,  1,  1,  byBits)  ; 


The  Color  Bitmap  Format 

An  old-style  color  bitmap  is  a  little  more  complex  and  extremely  device  dependent.  A  color 
bitmap  is  organized  to  facilitate  the  transfer  of  the  bits  to  a  particular  output  device. 
Whether  the  bitmap  is  organized  as  a  series  of  color  planes  or  as  multiple  color  bits  per 
pixel  depends  on  the  device  for  which  the  bitmap  is  suitable. 

Let’s  look  first  at  a  bitmap  that  has  a  bmBitsPixelv alue  of  1  (which  means  that  it  has  1 
color  bit  per  pixel)  but  a  bmPlanesv alue  greater  than  1.  A  color  bitmap  for  the  EGA  or  VGA 
is  a  good  example.  Windows  uses  the  four  color  planes  of  the  EGA  or  VGA  to  display  16 
colors,  so  bmPlanesis  4.  The  array  of  bits  begins  with  the  top  scan  line.  The  color  planes  for 
each  scan  line  are  stored  sequentially — the  red  plane  first,  the  green  plane,  the  blue  plane, 
and  the  intensity  plane.  The  bitmap  then  continues  with  the  second  scan  line. 

A  bitmap  can  also  represent  color  as  a  multiple  number  of  bits  per  pixel.  Suppose  a 
device  (such  as  the  IBM  8514/A)  can  represent  256  colors  using  8  color  bits  (1  byte)  per 
pixel.  For  each  scan  line,  the  first  byte  represents  the  color  for  the  leftmost  pixel,  the  sec¬ 
ond  byte  represents  the  color  for  the  next  pixel,  and  so  forth.  The  bmWidthBytes  value 
in  the  BITMAP  structure  reflects  the  increased  byte  width  of  each  scan  line,  but  the 
bmWidth  value  is  still  the  number  of  pixels  per  scan  line. 
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Here’s  the  catch:  Nothing  in  the  bitmap  specifies  how  these  multiple  color  planes  or 
multiple  color  bits  correspond  to  actual  display  colors.  A  particular  color  bitmap  is  suitable 
only  for  an  output  device  with  display  memory  organized  like  the  bitmap.  For  instance, 
suppose  you  have  a  device  that  stores  color  information  using  8  bits  per  pixel,  but  the  256 
values  are  interpreted  by  the  device  differently  than  by  an  8514/A.  This  is  perfectly  legiti¬ 
mate,  but  a  bitmap  created  for  the  8514/A  would  have  incorrect  colors  on  the  other  device. 

Thus,  creating  an  initialized  color  bitmap  using  CreateBitmap  or  CreateBitmapIn- 
direct  is  not  recommended.  You  should  use  these  functions  only  for  creating  initialized 
or  uninitialized  monochrome  bitmaps. 

To  create  a  color  bitmap,  use  CreateCompatibleBitmap ,  which  ensures  that  the  for¬ 
mat  is  compatible  with  a  real  graphics  output  device.  You  get  an  image  into  a  color  bitmap 
by  selecting  it  into  a  memory  device  context  (described  shortly)  and  then  drawing  on  this 
device  context  or  by  using  the  BitBlt  function. 

To  create  a  color  bitmap  that  is  not  necessarily  compatible  with  a  real  graphics  output 
device,  use  DIBs. 

The  Dimensions  of  a  Bitmap 

Two  other  functions  connected  with  bitmaps  are  the  source  of  some  confusion.  These  are: 
SetBitmapDimension  (hBitmap,  xDimension,  yDimension)  ; 

and: 


dwDimension  =  GetBitmapDimension  (hBitmap)  ; 

The  xDimension  and  yDimension  values  (encoded  as  the  low  and  high  words  in  the 
dwDimension  value  returned  from  GetBitmapDimension)  are  the  width  and  height  of  the 
bitmap  in  units  of  0.1  mm,  which  correspond  to  logical  units  in  the  MM-LOMETRIC  map¬ 
ping  mode.  GDI  itself  doesn’t  use  these  dimensions.  They  are  part  of  neither  the  BITMAP 
structure  nor  the  bitmap  file  format.  However,  two  cooperating  applications  could  use 
these  dimensions  to  aid  in  the  scaling  of  bitmaps  that  are  exchanged  through  the  clipboard 
or  by  other  means. 

THE  MEMORY  DEVICE  CONTEXT 

Two  functions — SetDIBitsToDevice  and  StretchDIBits — allow  you  to  render  an  array  of 
bits  on  an  output  device.  However,  if  you  have  a  handle  to  a  bitmap,  there  is  no  function  to 
draw  the  bitmap  on  the  display  surface  of  a  device  context.  You’ll  search  in  vain  for  a  func¬ 
tion  that  looks  like  this: 

DrawBitmap  (hdc,  hBitmap,  xStart,  yStart)  ;  //  No  such  function!!! 

This  function  would  copy  a  bitmap  to  the  device  context  represented  by  hdc  beginning  at 
the  logical  point  ( xStart ,  yStart).  We’ll  write  our  own  DrawBitmap  function  later  in  this 
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chapter.  First,  however,  you  need  to  become  familiar  with  several  concepts,  starting  with 
the  memory  device  context. 

A  memory  device  context  is  a  device  context  that  has  a  “display  surface”  that  exists 
only  in  memory.  You  can  create  a  memory  device  context  using  the  function: 

hdcMem  =  CreateCompatibleDC  (hdc)  ; 

The  hdc  handle  is  a  handle  to  an  existing  valid  device  context.  The  function  returns  a 
handle  to  the  memory  device  context.  Upon  creation  of  the  memory  device  context,  all  the 
attributes  are  set  to  the  normal  default  values.  You  can  do  almost  anything  you  want  with 
this  memory  device  context.  You  can  set  the  attributes  to  nondefault  values,  obtain  the  cur¬ 
rent  settings  of  the  attributes,  and  select  pens,  brushes,  regions  into  it.  And  yes,  you  can 
even  draw  on  it.  But  it  doesn’t  make  much  sense  to  do  so  just  yet.  Here’s  why. 

When  you  first  create  a  memory  device  context,  it  has  a  “display  surface”  that  con¬ 
tains  exactly  1  monochrome  pixel.  That  is  a  very  small  display  surface.  (Don’t  rely  on  Get - 
DeviceCaps  to  tell  you  this.  The  HORZSIZE,  VERTSIZE,  HORZRES,  VERTRES,  BITSPIXEL, 
and  PLANES  values  for  hdcMem  will  all  be  set  to  the  values  associated  with  the  original 
hdc.  If  GetDeviceCaps  really  returned  the  correct  values  associated  with  the  memory 
device  context  when  it  is  first  created,  then  the  HORZRES,  VERTRES,  BITSPIXEL,  and 
PLANES  indexes  would  all  return  1.)  What  you  need  to  do  is  make  the  display  surface 
of  the  memory  device  context  larger.  You  do  this  by  selecting  a  bitmap  into  the  device 
context: 

SelectObject  (hdcMem,  hBitmap)  ; 

Now  the  display  surface  of  hdcMem  has  the  same  width,  height,  and  color  organization  as 
the  bitmap  referenced  by  hBitmap.  With  the  default  window  and  viewport  origins,  the 
logical  point  (0,  0)  of  the  memory  device  context  corresponds  to  the  upper  left  corner  of 
the  bitmap. 

If  the  bitmap  had  some  kind  of  picture  on  it,  then  that  picture  is  now  part  of  the 
memory  device  context’s  display  surface.  Any  changes  you  make  to  that  bitmap  (for  in¬ 
stance,  by  using  SetBitmapBits  to  set  a  different  array  of  bits  to  the  bitmap)  are  reflected  in 
this  display  surface.  Anything  you  draw  on  the  memory  device  context  is  actually  drawn 
on  the  bitmap.  In  short,  the  bitmap  is  the  display  surface  of  the  memory  device  context. 

Earlier  I  discussed  the  various  functions  to  create  bitmaps.  One  of  them  is: 

hBitmap  =  CreateCompatibl eBi tmap  (hdc,  xWidth,  yHeight)  ; 

If  hdc  is  the  handle  to  the  normal  device  context  for  a  screen  or  a  printer,  then  the  number 
of  color  planes  and  number  of  bits  per  pixel  of  this  bitmap  are  the  same  as  for  the  device. 
However,  if  hdc  is  the  handle  to  a  memory  device  context  (and  no  bitmap  has  yet  been  se¬ 
lected  into  the  memory  device  context),  then  CreateCompatihleBitmap  returns  a  mono¬ 
chrome  bitmap  that  is  xWidth  pixels  wide  and  yHeight  pixels  high. 
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A  bitmap  is  one  of  six  GDI  objects.  You  saw  in  Chapter  12  how  to  use  SelectObject  to 
select  a  pen,  brush,  or  region  into  a  device  context,  and  in  Chapter  14  you’ll  learn  how  to 
use  this  function  to  select  a  font  into  a  device  context.  You  can  use  SelectObject  to  select 
these  four  GDI  objects  into  a  memory  device  context  also.  However,  you  cannot  select  a 
bitmap  into  a  normal  device  context,  only  into  a  memory  device  context. 

When  you’ve  finished  with  the  memory  device  context,  you  must  delete  it: 

DeleteDC  (hdcMem)  ; 

Well,  you  may  say,  this  is  all  very  nice,  but  we  haven’t  yet  solved  the  problem  of  get¬ 
ting  the  bitmap  on  the  display.  All  we’ve  done  is  select  it  into  a  memory  device  context. 
Now  what?  Now  we  have  to  learn  how  to  “bit”  (pronounced  “blit”)  the  bits  from  one  device 
context  to  another. 


THE  MIGHTY  BLT 

Computer  graphics  involves  writing  pixels  to  a  display  device.  In  Chapter  12  we  looked  at 
the  more  refined  ways  of  doing  this,  but  for  power  pixel  manipulation,  nothing  in  Windows 
comes  close  to  BitBlt  and  its  two  cousins,  PatBlt  and  StretchBlt.  BitBlt  (pronounced  “bit 
blit”)  stands  for  “bit-block  transfer.”  BitBlt  is  a  pixel-mover,  or  (more  vividly)  a  raster- 
blaster.  The  simple  word  “transfer”  doesn’t  really  do  justice  to  BitBlt .  It  does  more  than  a 
transfer — it  actually  does  a  logical  combination  of  three  sets  of  pixels  using  1  of  256  differ¬ 
ent  types  of  raster  operations. 

The  PatBlt  Function 

PatBlt  (“pattern  block  transfer”)  is  the  simplest  of  the  three  “bit”  functions.  It’s  really  quite 
different  from  BitBlt  and  StretchBlt  in  that  it  uses  only  one  device  context.  But  PatBlt  is 
nonetheless  a  reasonable  place  to  begin. 

In  Chapter  12  you  encountered  the  device  context  attribute  called  the  drawing  mode. 
This  attribute  can  be  set  to  1  of  16  binary  raster  operation  (ROP2)  codes.  When  you  draw  a 
line,  the  drawing  mode  determines  the  type  of  logical  operation  that  Windows  performs 
on  the  pixels  of  the  pen  and  the  pixels  of  the  device  context  destination.  PatBlt  is  similar  to 
the  drawing  mode  except  that  it  alters  a  rectangular  area  of  the  device  context  destination 
rather  than  merely  a  line.  It  performs  a  logical  operation  involving  the  pixels  in  this  rect¬ 
angle  and  a  “pattern.”  This  “pattern”  is  nothing  new — pattern  is  simply  another  name  for 
a  brush.  For  this  pattern,  PatBlt  uses  the  brush  currently  selected  in  the  device  context. 
The  syntax  of  PatBlt  is: 

PatBlt  (hdc,  xDest,  yDest,  xWidth,  yHeight,  dwROP)  ; 

The  xDest ,  yDest ,  xWidth,  and  yHeight  parameters  are  in  logical  units.  The  logical  point 
(. xDest ,  yDest)  specifies  the  upper  left  corner  of  a  rectangle.  The  rectangle  is  xWidth  units 
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wide  and  yHeight  units  high.  (See  the  following  section,  entitled  “Bit  Coordinates,”  for  a 
more  precise  definition  of  these  values.)  This  is  the  rectangular  area  that  PatBlt  alters.  The 
logical  operation  that  PatBlt  performs  on  the  brush  and  the  destination  device  context  is 
determined  by  the  dwROP  parameter,  which  is  a  doubleword  (32-bit  integer)  ROP  code — 
not  one  of  the  ROP2  codes  used  for  the  drawing  mode. 

Windows  has  256  ROP  codes.  These  define  all  possible  logical  combinations  of  a 
source  display  area,  a  destination  display  area,  and  a  pattern  (or  brush).  The  device  driver 
for  the  video  display  supports  all  256  raster  operations  through  the  use  of  a  “compiler”  of 
sorts.  This  compiler  uses  the  32-bit  ROP  code  to  create  a  set  of  machine-language  instruc¬ 
tions  on  the  stack  that  can  carry  out  this  logical  operation  on  the  pixels  of  the  display;  it 
then  executes  these  instructions.  The  high  word  of  the  32-bit  ROP  code  is  a  number  be¬ 
tween  0  and  255.  The  low  word  is  a  number  that  assists  the  device  driver  “compiler”  in 
constructing  the  machine  code  for  the  logical  operation.  Fifteen  of  the  256  ROP  codes  have 
names.  If  you  want  to  use  any  of  the  others,  you’ll  have  to  look  up  the  number  in  the  table  in 
the  Programmer’s  Reference  included  with  the  Windows  Software  Development  Kit. 

Because  the  PatBlt  function  uses  only  a  destination  device  context  and  a  pattern  (and 
not  a  source  device  context),  it  can  accept  only  a  subset  of  these  256  ROP  codes — that  is, 
the  16  ROP  codes  that  use  only  the  destination  device  context  and  a  pattern.  The  16  raster 
operations  supported  by  PatBlt  are  shown  in  the  table  below.  You’ll  notice  that  this  is  simi¬ 
lar  to  the  table  showing  ROP2  codes  on  page  551  of  Chapter  12. 


Pattern  (P): 

1 

1 

0 

0 

Boolean 

ROP 

Destination  (D): 

1 

0 

1 

0 

Operation 

Code 

Name 

Result: 

0 

0 

0 

0 

0 

000042 

BLACKNESS 

0 

0 

0 

1 

~(p :  D) 

0500A9 

0 

0 

1 

0 

~P  &  D 

0A0329 

0 

0 

1 

1 

~P 

0F0001 

0 

1 

0 

0 

P&-D 

500325 

0 

1 

0 

1 

~D 

550009 

DSTINVERT 

0 

1 

1 

0 

PAD 

5A0049 

PATINVERT 

0 

1 

1 

1 

~(P  &  D) 

5FOOE9 

1 

0 

0 

0 

P&D 

A000C9 

1 

0 

0 

1 

~(P  A  D) 

A50065 

1 

0 

1 

0 

D 

AA0029 

1 

0 

1 

1 

~P!D 

AF0229 

1 

1 

0 

0 

P 

F00021 

PATCOPY 

1 

1 

0 

1 

P!~D 

F50225 

1 

1 

1 

0 

P !  D 

FA0089 

1 

1 

1 

1 

1 

FF0062 

WHITENESS 
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For  a  monochrome  device  context,  a  1  bit  corresponds  to  a  white  pixel  and  a  0  bit  to  a 
black  pixel.  Destinations  and  patterns  that  are  either  pure  black  or  pure  white  are  the 
easiest  to  consider  when  you  start  thinking  about  PatBlt.  For  instance,  if  you  call: 

PatBlt  (hdc,  xDest,  yDest,  xWidth,  yHeight,  0x5F00E9L)  ; 

then  the  rectangular  area  that  begins  at  the  logical  point  ( xDest ,  yDest)  and  that  is  xWidth 
pixels  wide  and  yHeight  pixels  high  will  be  colored  black  only  if  the  destination  was 
originally  white  and  you  had  WHITE_BRUSH  selected  in  the  device  context.  Otherwise, 
the  destination  will  be  colored  white.  Of  course,  even  in  a  monochrome  device  context, 
destinations  and  brushes  can  be  dithered  combinations  of  black  and  white  pixels.  In  this 
case,  Windows  performs  the  logical  combination  on  a  pixel-by-pixel  basis,  which  can  lead 
to  some  odd  results.  For  instance,  if  your  destination  has  been  colored  with  GRAY_BRUSH, 
and  GRAY_BRUSH  is  also  the  current  brush  selected  into  the  device  context,  then: 

PatBlt  (hdc,  xDest,  yDest,  xWidth,  yHeight,  PATINVERT)  ; 

will  set  the  destination  to  either  pure  white  or  pure  black,  depending  on  how  the  dithered 
pixels  of  the  destination  coincide  with  the  dithered  pixels  of  the  brush. 

Color  introduces  more  complexities.  Windows  performs  the  logical  operation  for 
each  color  plane  separately  or  each  set  of  color  bits  separately,  depending  on  how  the 
memory  of  the  device  is  organized. 

Some  of  the  more  common  uses  of  PatBlt  are  shown  below.  If  you  want  to  draw  a 
black  rectangle,  you  call: 

PatBlt  (hdc,  xDest,  yDest,  xWidth,  yHeight,  BLACKNESS)  ; 

To  draw  a  white  rectangle,  use: 

PatBlt  (hdc,  xDest,  yDest,  xWidth,  yHeight,  WHITENESS)  ; 

The  function: 

PatBlt  (hdc,  xDest,  yDest,  xWidth,  yHeight,  DSTINVERT)  ; 

always  inverts  the  colors  of  the  rectangle.  If  WHITE-BRUSH  is  currently  selected  in  the 
device  context,  then  the  function: 

PatBlt  (hdc,  xDest,  yDest,  xWidth,  yHeight,  PATINVERT)  ; 

also  inverts  the  rectangle. 

You’ll  recall  that  the  FillRect  function  fills  in  a  rectangular  area  with  a  brush: 

Fill Rect  (hdc,  &rect,  hBrush)  ; 

The  FillRect  function  is  equivalent  to  the  following  code: 

hBrush  =  SelectObject  (hdc,  hBrush)  ; 

PatBlt  (hdc,  rect. left,  rect. top, 

rect. right  -  rect. left, 

rect. bottom  -  rect. top,  PATCOPY)  ; 

SelectObject  (hdc,  hBrush)  ; 


627 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


In  fact,  this  code  is  what  Windows  uses  to  execute  the  FillRect  function.  When  you  call: 

InvertRect  (hdc,  &rect)  ; 

Windows  translates  it  into  the  function: 

PatBlt  (hdc,  rect.left,  rect.top, 

rect. right  -  rect.left, 

rect. bottom  -  rect.top,  DSTINVERT)  ; 

Bit  Coordinates 

When  I  introduced  the  syntax  of  the  PatBlt  function,  I  said  that  the  point  ( xDest ,  yDest) 
specifies  the  upper  left  corner  of  a  rectangle  and  that  this  rectangle  is  xWidth  units  wide 
and  yHeight  units  high.  Actually,  although  that’s  also  what  the  Windows  documentation 
says,  the  statement  is  not  entirely  accurate.  Before  we  proceed  any  further,  I  need  to  clear 
up  some  confusion  concerning  the  £>/r  functions  and  coordinates. 

BitBlt,  PatBlt ,  and  Stretch  Bit  axe  the  only  GDI  drawing  functions  that  specify  logical 
rectangular  coordinates  in  terms  of  a  logical  width  and  height  measured  from  a  single  cor¬ 
ner.  All  the  other  GDI  drawing  functions  that  use  rectangular  bounding  boxes  require  that 
coordinates  be  specified  in  terms  of  an  upper  left  corner  and  a  lower  right  corner.  For  the 
MM-TEXT  mapping  mode,  the  above  description  of  the  PatBlt  parameters  is  accurate.  For 
the  metric  mapping  modes,  however,  it’s  not.  If  you  use  positive  values  of  xWidth  and 
yHeight ,  then  the  point  ( xDest ,  yDest )  will  be  the  lower  left  corner  of  the  rectangle.  If  you 
want  ( xDest ,  yDest )  to  be  the  upper  left  corner  of  the  rectangle,  the  yHeight  parameter  must 
be  set  to  the  negative  height  of  the  rectangle. 

To  be  more  precise,  the  rectangle  that  PatBlt  colors  has  a  logical  width  given  by  the 
absolute  value  of  xWidth  and  a  logical  height  given  by  the  absolute  value  of  yHeight.  These 
two  parameters  can  be  negative.  The  rectangle  is  defined  by  two  corners  given  by  the  logi¬ 
cal  points  (xDest,  yDest )  and  (xDest  +  xWidth ,  yDest  +  yHeight ).  The  upper  left  corner  of  the 
rectangle  is  always  included  in  the  area  that  PatBlt  modifies.  The  lower  right  corner  is  out¬ 
side  the  rectangle.  Depending  on  the  mapping  mode  and  the  signs  of  the  xWidth  and 
yHeight  parameters,  the  upper  left  corner  of  this  rectangle  could  be  the  point: 

(xDest,  yDest) 


or: 


(xDest,  yDest  +  yHeight) 


or: 


(xDest  +  xWidth,  yDest) 
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or: 


(xDest  +  xWidth,  yDest  +  yHeight) 


If  you’ve  set  the  mapping  mode  to  MM_LOENGLISH  and  you  want  to  use  PatBlt  on 
the  square  inch  at  the  upper  left  corner  of  the  client  area,  you  can  use: 

PatBlt  (hdc,  0,  0,  100 ,  -100,  dwROP)  ; 

or: 

PatBlt  (hdc.  0.  -100,  100,  100,  dwROP)  ; 
or: 

PatBlt  (hdc.  100,  0,  -100,  -100,  dwROP)  ; 


or: 

PatBlt  (hdc,  100,  -100,  -100,  100,  dwROP)  ; 


The  easiest  way  to  set  the  correct  parameters  to  PatBlt  is  to  set  xDest  and  yDest  to  the 
upper  left  corner  of  the  rectangle.  If  your  mapping  mode  defines  ^-coordinates  as  increas¬ 
ing  as  you  move  up  the  display,  use  a  negative  value  for  the  yHeight  parameter.  If  your  map¬ 
ping  mode  defines  x- coordinates  as  increasing  to  the  left  (which  is  almost  unheard  of),  use 
a  negative  value  for  the  xWidth  parameter. 


Transferring  Bits  with  BitBIt 

In  one  sense,  BitBIt  is  a  superset  of  PatBlt .  It  does  everything  PatBlt  does  but  also  intro¬ 
duces  a  second  device  context  into  the  logical  operation.  Here’s  the  general  syntax: 

BitBIt  (hdcDest,  xDest,  yDest,  xWidth,  yHeight, 
hdcSrc,  xSrc,  ySrc,  dwROP)  ; 

The  BitBIt  call  modifies  the  destination  device  context  (whose  handle  is  hdcDest)  within 
the  rectangle  defined  by  the  logical  point  ( xDest ,  yDest)  and  the  xWidth  and  yHeight  pa¬ 
rameters,  both  of  which  are  in  logical  units.  These  parameters  define  a  rectangle  as  de¬ 
scribed  in  the  previous  section.  BitBIt  also  uses  a  rectangle  in  a  source  device  context 
(whose  handle  is  SrcDC).  This  rectangle  begins  at  the  logical  point  ( xSrc ,  ySrc)  and  is  also 
xWidth  logical  units  wide  and  yHeight  l ogical  units  high. 

BitBIt  performs  a  logical  combination  of  three  elements:  the  brush  selected  into  the 
destination  device  context,  the  pixels  in  the  source  device  context  rectangle,  and  the  pix¬ 
els  in  the  destination  device  context  rectangle.  The  result  is  written  to  the  destination  de¬ 
vice  context  rectangle.  You  can  use  any  of  the  256  ROP  codes  for  the  dwROP  parameter  to 
BitBIt.  The  15  ROP  codes  that  have  names  are  shown  in  the  table  on  the  following  page.  If 
you  need  to  use  any  of  the  others,  you  can  look  them  up  in  the  Programmer’s  Reference. 
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Pattern  (P): 

1 

1 

/ 

1 

0 

0 

0 

0 

Source  (S): 

1 

1 

0 

0 

1 

1 

0 

0 

Boolean 

ROP 

Destination  (D): 

1 

0 

1 

0 

1 

0 

1 

0 

Operation 

Code 

Name 

Result: 

0 

0 

0 

0 

0 

0 

0 

0 

0 

000042 

BLACKNESS 

0 

0 

0 

1 

0 

0 

0 

1 

~(s:d) 

1100A6 

NOTSRCERASE 

0 

0 

1 

1 

0 

0 

1 

1 

~s 

330008 

NOTSRCCOPY 

0 

1 

0 

0 

0 

1 

0 

0 

S&-D 

440328 

SRCERASE 

0 

1 

0 

1 

0 

1 

0 

1 

~D 

550009 

DSTINVERT 

0 

1 

0 

1 

1 

0 

1 

0 

PAD 

5A0049 

PATINVERT 

0 

1 

1 

0 

0 

1 

1 

0 

SAD 

660046 

SRCINVERT 

1 

0 

0 

0 

1 

0 

0 

0 

S&D 

8800C6 

SRC  AND 

1 

0 

1 

1 

1 

0 

1 

1 

~S !  D 

BB0226 

MERGEPAINT 

1 

1 

0 

0 

0 

0 

0 

0 

P&S 

COOOCA 

MERGECOPY 

1 

1 

0 

0 

1 

1 

0 

0 

S 

CC0020 

SRCCOPY 

1 

1 

1 

0 

1 

1 

1 

0 

SID 

EE0086 

SRCPAINT 

1 

1 

1 

1 

0 

0 

0 

0 

P 

F00021 

PATCOPY 

1 

1 

1 

1 

1 

0 

1 

1 

P !  ~S  1  D 

FB0A09 

PATPAINT 

1 

1 

1 

1 

1 

1 

1 

1 

1 

FF0062 

WHITENESS 

Look  at  the  eight  0’s  and  l’s  that  show  the  result  of  the  logical  combination.  The  two- 
digit  hexadecimal  number  that  corresponds  to  these  bits  is  the  high  word  of  the  ROP  code. 
If  we  can  create  a  table  of  the  result  we  want  from  the  pattern,  source,  and  destination,  we 
can  easily  determine  the  ROP  code  from  the  table  of  ROP  codes  in  the  Programmer’s  Refer¬ 
ence.  We’ll  be  doing  this  a  little  later.  If  you  use  1  of  the  16  ROP  codes  shown  in  the  table  on 
page  626,  then  you  can  use  PatBlt  instead  of  BitBlt,  because  you’re  not  referencing  a 
source  device  context. 

You  can  set  hdcSrc  and  hdcDest  to  the  same  device  context  handle,  in  which  case 
BitBlt  will  perform  a  logical  combination  of  the  destination  rectangle,  the  source  rect¬ 
angle,  and  the  current  brush  selected  into  the  device  context.  However,  it’s  a  little  risky  to 
do  this  in  your  client-area  device  context.  If  part  of  the  source  rectangle  is  covered  by  an¬ 
other  window,  then  Windows  will  use  the  pixels  of  this  other  window  as  the  source.  Win¬ 
dows  doesn’t  know  what’s  underneath  that  other  window  in  your  client  area. 

However,  examples  of  the  BitBlt  function  using  the  same  device  context  for  the 
source  and  destination  are  the  easiest  to  grasp.  The  function: 

BitBlt  (hdc,  100,  0,  50,  100,  hdc,  0,  0,  SRCCOPY)  ; 

copies  the  rectangle  beginning  at  logical  point  (0,  0)  that  is  50  logical  units  wide  and  100 
logical  units  high  to  the  rectangular  area  beginning  at  the  logical  point  (100,  0). 
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The  DrawBitmap  Function 

BitBlt  becomes  most  valuable  in  working  with  bitmaps  that  have  been  selected  into  a 
memory  device  context.  When  you  perform  a  “bit-block  transfer”  from  the  memory  device 
context  to  a  device  context  for  your  client  area,  the  bitmap  selected  in  the  memory  device 
context  is  transferred  to  your  client  area. 

Earlier  I  mentioned  a  hypothetical  DrawBitmap  function  that  would  draw  a  bitmap 
on  a  display  surface.  Such  a  function  would  have  the  syntax: 

DrawBitmap  (hdc,  hBitmap,  xStart,  yStart)  ; 

I  promised  we’d  write  a  DrawBitmap  function;  here  it  is: 

void  DrawBitmap  (HDC  hdc,  HBITMAP  hBitmap,  short  xStart,  short  yStart) 

{ 

BITMAP  bm  ; 

HDC  hdcMem  ; 

DWORD  dwSize  ; 

POINT  ptSize,  ptOrg  ; 

hdcMem  =  CreateCompati bl eDC  (hdc)  ; 

SelectObject  (hdcMem,  hBitmap)  ; 

SetMapMode  (hdcMem,  GetMapMode  (hdc))  ; 

GetObject  (hBitmap,  sizeof  (BITMAP),  ( LPSTR)  &bm)  ; 
ptSize. x  =  bm.bmWidth  ; 
ptSize. y  =  bm.bmHeight  ; 

DPtoLP  (hdc,  &ptSize,  1)  ; 

ptOrg. x  =  0  ; 
ptOrg. y  =  0  ; 

DPtoLP  (hdcMem,  &ptOrg,  1)  ; 

BitBlt  (hdc,  xStart,  yStart,  ptSize. x,  ptSize. y, 
hdcMem,  ptOrg. x,  ptOrg. y,  SRCCOPY)  ; 

DeleteDC  (hdcMem)  ; 

} 

I’m  assuming  here  that  you  don’t  want  the  height  or  width  of  the  bitmap  stretched  or  com¬ 
pressed  in  any  way.  That  is,  if  your  bitmap  is  100  pixels  wide,  you  want  it  to  cover  a  100- 
pixel-wide  rectangle  of  your  client  area  regardless  of  the  mapping  mode. 

DrawBitmap  first  creates  a  memory  device  context  using  CreateCompatibleDC  and 
then  selects  the  bitmap  into  it  with  SelectObject.  The  mapping  mode  of  the  memory  device 
context  is  set  to  the  same  mapping  mode  as  the  video  device  context.  Because  BitBlt  works 
with  logical  coordinates  and  logical  sizes  and  you  don’t  want  the  bitmap  stretched  or  com¬ 
pressed,  the  xWidth  and  yHeight  parameters  to  BitBlt  must  be  logical  units  that  correspond 
to  the  physical  pixel  size  of  the  bitmap.  For  this  reason,  DrawBitmap  gets  the  dimensions 
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of  the  bitmap  using  GetObject  and  makes  a  POINT  structure  out  of  the  width  and  height.  It 
then  converts  this  point  to  logical  coordinates.  This  is  done  similarly  for  the  origin  of  the 
bitmap — the  point  (0,  0)  in  device  coordinates. 

Notice  that  it  doesn’t  matter  which  brush  is  currently  selected  into  the  destination 
device  context  ( hdc ),  because  SRCCOPY  doesn’t  use  the  brush. 

Using  Different  ROP  Codes 

SRCCOPY  is  definitely  the  most  popular  divROP  parameter  to  BitBlt ,  and  you  may  be  hard- 
pressed  to  find  uses  for  the  other  255  ROP  codes.  So  I’ll  give  you  a  couple  of  examples  in 
which  other  ROP  codes  show  their  stuff. 

In  the  first  example,  you  have  a  monochrome  bitmap  that  you  want  to  transfer  to  the 
screen.  However,  you  want  to  display  the  bitmap  so  that  the  black  (0)  bits  don’t  affect 
anything  currently  on  the  client  area.  Moreover,  you  want  all  the  white  (1)  bits  to  color  the 
client  area  with  a  brush,  perhaps  a  colored  brush  created  from  CreateSolidBrush.  How  do 
you  do  it? 

I’ll  assume  that  you’re  working  in  the  MM_TEXT  mapping  mode  and  that  you  want  to 
write  the  bitmap  starting  at  the  point  (xStart,  yStart)  in  your  client  area.  You  already  have  a 
handle  to  the  monochrome  bitmap  ( hBitmap )  and  a  handle  to  the  colored  brush  ( bBrush ). 
You  know  the  width  and  height  of  the  bitmap  and  have  them  stored  in  a  BITMAP  structure 
named  bm.  Here’s  the  code: 

hdcMem  =  CreateCompati bl eDC  (hdc)  ; 

SelectObject  (hdcMem,  hBitmap)  ; 

hBrush  =  SelectObject  (hdc,  hBrush)  ; 

BitBlt  (hdc,  xStart,  yStart,  bm.bmWidth,  bm.bmHeight, 
hdcMem,  0,  0,  0xE20746L)  ; 

SelectObject  (hdc,  hBrush)  ; 

DeleteDC  (hdcMem)  ; 

BitBlt  performs  a  logical  combination  of  a  destination  device  context  ( hdc ),  a  source 
device  context  ( hdcMem. ),  and  the  brush  currently  selected  in  the  destination  device  con¬ 
text.  So  you  create  a  memory  device  context,  select  the  bitmap  into  it,  select  the  colored 
brush  into  your  client-area  display  context,  and  call  BitBlt.  Then  you  select  the  original 
brush  into  your  display  device  context  and  delete  the  memory  device  context. 

The  only  puzzling  part  of  this  code  is  the  ROP  code  0xE20746.  This  ROP  code  causes 
Windows  to  perform  the  logical  operation: 

((Destination  a  Pattern)  &  Source)  a  Destination 


632 


Chapter  13:  Bits,  Bits,  and  Metafiles 


Still  not  obvious?  Try  this  approach:  Copy  this  part  of  the  table  on  page  630: 


Pattern: 

1 

1 

1 

1 

0 

0 

0 

0 

Source: 

1 

1 

0 

0 

1 

1 

0 

0 

Destination: 

1 

0 

1 

0 

1 

0 

1 

0 

Result: 

? 

? 

7 

7 

7 

7 

7 

7 

For  every  black  bit  in 

the  bitmap  (which  will  be  selected  into  the  source  memory  device 

context),  you 

want  the  destination  device 

context  to  be  unchanged.  This  means  that 

everywhere  the  Source  is  0,  you  want  the  Result  to  be  the  same  bit  as  the  Destination: 

Pattern: 

1 

1 

1 

1 

0 

0 

0 

0 

Source: 

1 

1 

0 

0 

1 

1 

0 

0 

Destination: 

1 

0 

1 

0 

1 

0 

1 

0 

Result: 

7 

7 

1 

0 

7 

7 

1 

0 

We’re  halfway  there.  For  every  white  bit  in 

the  bitmap,  you  want  the  destination  device 

context  to  be  colored  with  the  pattern. 

The  brush 

you 

select  into  the  destination  device 

context  is  this  pattern.  So  everywhere  the  Source  is  1,  you  want  the  Result  to  be  the  Pattern: 

Pattern: 

1 

1 

1 

1 

0 

0 

0 

0 

Source: 

1 

1 

0 

0 

1 

1 

0 

0 

Destination: 

1 

0 

1 

0 

1 

0 

1 

0 

Result- 

1 

1 

1 

0 

0 

0 

1 

0 

This  means  that  the  high  word  of  the  ROP  code  is  0xE2.  You  can  look  that  up  in  the  ROP 
table  in  the  Programmer’s  Reference  and  find  that  the  full  ROP  code  is  0xE20746. 

Perhaps  at  this  point  you  discover  that  you  mixed  up  the  white  and  black  bits  when 
you  created  the  bitmap  in  SDKPAINT.  That’s  easy  to  fix.  It’s  merely  a  different  logical 
operation: 


Pattern: 

Source: 

Destination: 

Result: 


1  1 
1  1 
1  0 
1  0 


1  1 
0  0 
1  0 
1  1 


0  0 
1  1 
1  0 
1  0 


0  0 
0  0 
1  0 
0  0 


Now  the  high  word  of  the  ROP  code  is  0xB8,  and  the  entire  ROP  code  is  0xB8074A,  which 
performs  the  logical  operation: 


((Destination  A  Pattern)  &  Source)  A  Pattern 


Here’s  the  second  example:  Back  in  Chapter  8, 1  discussed  the  two  bitmaps  that  make 
up  icons  and  cursors.  The  use  of  two  bitmaps  allows  these  figures  to  be  “transparent”  in 
spots  or  to  invert  the  display  surface  underneath.  For  a  monochrome  icon  or  cursor,  the 


two  bitmaps  are  coded  as 

follows: 

Bitmap  1: 

0 

0 

1 

1 

Bitmap  2: 

0 

1 

0 

1  • 

Result: 

Black 

White 

Screen 

Inverse  Screen 
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Windows  selects  Bitmap  1  into  a  memory  device  context  and  uses  BitBlt  with  a  ROP  code 
called  SRCAND  to  transfer  the  bitmap  to  the  display.  This  ROP  code  performs  the  logical 
operation: 

Destination  &  Source 

In  Bitmap  1,  the  destination  is  left  unchanged  for  1  bits  and  set  to  0  for  0  bits.  Windows  then 
selects  Bitmap  2  into  the  device  context  and  uses  BitBlt  with  SRCINVERT.  The  logical 
operation  is: 

Destination  a  Source 

In  Bitmap  2,  this  leaves  the  destination  unchanged  for  all  0  bits  and  inverts  the  destination 
for  all  1  bits. 

Look  at  the  first  and  second  columns  of  the  table:  Bitmap  1  with  SRCAND  blacks  out 
the  bits,  and  Bitmap  2  with  SRCINVERT  turns  selected  bits  to  white  by  inverting  the  black 
bits.  These  operations  set  the  black  and  white  bits  that  make  up  the  icon  or  cursor.  Now 
look  at  the  third  and  fourth  columns  of  the  table:  Bitmap  1  with  SRCAND  leaves  the  display 
unchanged,  and  Bitmap  2  with  SRCINVERT  inverts  the  colors  of  selected  bits.  These 
operations  let  the  icon  or  cursor  be  transparent  or  invert  the  underlying  colors. 

Another  example  of  the  creative  use  of  ROP  codes  accompanies  the  description  of 
the  GrayString  function  in  Chapter  14. 

More  Fun  with  Memory  Device  Contexts 

We’ve  been  using  memory  device  contexts  to  transfer  an  existing  bitmap  to  the  display. 
You  can  also  use  memory  device  contexts  to  draw  on  the  surface  of  a  bitmap.  We  did  this  in 
the  GRAFMENU  program  in  Chapter  9,  when  we  used  the  GetBitmapFont  function  to 
make  menu  items  using  bitmaps.  First,  you  create  a  memory  device  context: 

hdcMem  =  CreateCompatibl eDC  (hdc)  ; 

Next,  you  create  a  bitmap  of  the  desired  size.  If  you  want  to  create  a  monochrome  bitmap, 
you  can  make  it  compatible  with  hdcMem. 

hBitmap  =  CreateCompati bl eBi tmap  (hdcMem,  xWidth,  yHeight)  ; 

Or  to  make  the  bitmap  have  the  same  color  organization  as  the  video  display,  you  can  make 
the  bitmap  compatible  with  hdc. 

hBitmap  =  CreateCompatibl eBi tmap  (hdc,  xWidth,  yHeight)  ; 

You  can  now  select  the  bitmap  into  the  memory  device  context: 

SelectObject  (hdcMem,  hBitmap)  ; 

Now  you  can  draw  on  this  memory  device  context  (and  by  extension,  the  bitmap) 
using  all  the  GDI  functions  we  discussed  in  Chapters  11  and  12  and  more  that  you’ll  encoun¬ 
ter  in  Chapter  14.  When  you  first  create  the  bitmap,  it  contains  random  bits,  so  you  may 
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want  to  begin  by  using  the  PatBlt  function  with  a  ROP  code  of  WHITENESS  or  BLACK¬ 
NESS  to  erase  the  background  of  the  memory  device  context. 

When  you’ve  finished  drawing  on  the  memory  device  context,  simply  delete  it: 

DeleteDC  (hdcMem)  ; 

Now  you’re  left  with  a  bitmap  containing  everything  you  drew  on  it  while  it  was  selected  in 
the  memory  device  context.  (We’ll  go  through  this  process  again  in  the  BOUNCE  program, 
shown  later  in  this  chapter.) 

The  SCRAMBLE  program,  shown  in  Figure  13-2,  uses  a  memory  device  context  as  a 
temporary  holding  space  for  BitBlt  operations  that  swap  the  contents  of  two  rectangles  of 
the  display. 

SCRAMBLE.MAK 

# 

#  SCRAMBLE.MAK  make  file 

# 

scramble.exe  :  scramble. obj  scramble. def 

$(WINLINK)  scramble,  scramble.  NUL.  $(WINLIB),  scramble 
rc  -t  scramble.exe 

scramble. obj  :  scramble. c 
$ ( W I NCC )  scramble. c 


SCRAMBLED 


/* 


SCRAMBLE. C  --  Scramble  (and  Unscramble)  Screen 
(c)  Charles  Petzold.  1992 


*/ 


♦include  <windows.h> 

♦include  <stdlib.h> 

♦define  NUM  200 

long  FAR  PASCAL  ^export  WndProc  (HWND,  UINT.  UINT.  LONG)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance.  HANDLE  hPrevInstance. 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  short  nKeep  [NUM] [4]  ; 

HDC  hdc  =  CreateDC  ("DISPLAY" .  NULL.  NULL,  NULL)  ; 


Figure  13-2.  The  SCRAMBLE  program.  (continued) 


635 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


HDC  hdcMem  =  CreateCompatibleDC  (hdc)  ; 

short  cxSize  =  GetSystemMetrics  (SM_CXSCREEN)  /  10  ; 

short  cySize  =  GetSystemMetrics  (SM_CYSCREEN)  /  10  ; 

HBITMAP  hBitmap  =  CreateCompatibleBitmap  (hdc,  cxSize,  cySize)  ; 

short  i,  j,  xl,  yl,  x2,  y2  ; 

SelectObject  (hdcMem,  hBitmap)  ; 

srand  (LOWORD  (GetCurrentTime  ()))  ; 


for  (i  =  0  ;  i  <  2  ;  i++) 

for  (j  =  0  ;  j  <  NUM  ;  j++) 

{ 

if  (1  ==  0) 

{ 

nKeep  [j]  [0]  =  xl  =  cxSize  *  (rand  0 

nKeep  [j]  [1]  =  yl  =  cySize  *  (rand  0 

nKeep  [j]  [2]  =  x2  =  cxSize  *  (rand  0 

nKeep  [j]  [3]  =  y2  =  cySize  *  (rand  0 

} 

else 


%  10) 
%  10) 
%  10) 
%  10) 


{ 

xl  =  nKeep  [NUM  -  1  -  j]  [0]  ; 
yl  =  nKeep  [NUM  -  1  -  j]  [1]  ; 
x2  =  nKeep  [NUM  -  1  -  j]  [2]  ; 
y2  =  nKeep  [NUM  -  1  -  j]  [3]  ; 

} 

BitBlt  (hdcMem,  0,  0,  cxSize,  cySize,  hdc,  xl,  yl,  SRCCOPY) 
BitBlt  (hdc,  xl,  yl,  cxSize,  cySize,  hdc,  x2,  y2,  SRCCOPY) 
BitBlt  (hdc,  x2,  y2,  cxSize,  cySize,  hdcMem,  0,  0,  SRCCOPY) 


DeleteDC  (hdcMem)  ; 
DeleteDC  (hdc)  ; 
DeleteObject  (hBitmap)  ; 

return  FALSE  ; 

} 


SCRAMBLE.DEF 


SCRAMBLE. DEF  module  definition  file 


NAME  SCRAMBLE 

DESCRIPTION  'Screen  Scrambler  (c)  Charles  Petzold,  1992' 


(continued) 
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EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


SCRAMBLE  doesn’t  have  a  window  procedure.  In  WinMain ,  it  obtains  a  device  con¬ 
text  for  the  entire  screen: 


hdc  =  CreateDC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 


and  also  a  memory  device  context: 

hdcMem  =  CreateCompatibl eDC  (hdc)  ; 

Then  it  determines  the  dimensions  of  the  full  screen  and  divides  them  by  10: 

xSize  =  GetSystemMetrics  (SM_CXSCREEN)  /  10  ; 
ySize  =  GetSystemMetrics  (SM_CYSCREEN)  /  10  ; 

The  program  uses  these  dimensions  to  create  a  bitmap: 

hBitmap  =  CreateCompatibl eBi tmap  (hdc,  xSize,  ySize)  ; 

and  selects  it  into  the  memory  device  context: 


SelectObject  (hdcMem,  hBitmap)  ; 

Using  the  normal  C  rand  (“random  number  generator")  function,  SCRAMBLE  finds 
four  random  values  that  are  multiples  of  the  x Size  and  ySize  values: 


xl  =  xSize  *  (rand 
yl  =  ySize  *  (rand 
x2  =  xSize  *  (rand 
y2  =  ySize  *  (rand 


0  %  10)  ; 
0  %  10)  ; 
0  %  10)  ; 
0  %  10)  ; 


The  program  swaps  two  rectangular  blocks  of  the  display  through  the  use  of  three  BitBlt 
functions.  The  first  copies  the  rectangle  beginning  at  point  {xl,  yl )  to  the  memory  device 
context: 


BitBlt  (hdcMem,  0,  0,  xSize,  ySize,  hdc,  xl,  yl,  SRCCOPY)  ; 

The  second  copies  the  rectangle  beginning  at  point  ( x2 ,  y2)  to  the  location  beginning  at 
point  {xl,  yl): 

BitBlt  (hdc,  xl,  yl,  xSize,  ySize,  hdc,  x2,  y2,  SRCCOPY)  ; 

The  third  copies  the  rectangle  in  the  memory  device  context  to  the  area  beginning  at  point 
{x2,  y2 ): 

BitBlt  (hdc,  x2,  y2,  xSize,  ySize,  hdcMem,  0,  0,  SRCCOPY)  ; 
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This  process  effectively  swaps  the  contents  of  the  two  rectangles  on  the  display. 
SCRAMBLE  does  this  200  times,  after  which  the  screen  should  be  thoroughly  scrambled. 
But  do  not  fear,  because  SCRAMBLE  keeps  track  of  this  mess  and  then  unscrambles  the 
screen,  returning  it  to  normal  before  exiting. 

You  can  also  use  memory  device  contexts  to  copy  the  contents  of  one  bitmap  to  an¬ 
other.  For  instance,  suppose  you  want  to  create  a  bitmap  that  contains  only  the  upper  left 
quadrant  of  another  bitmap.  If  the  original  bitmap  has  the  handle  hBitmap ,  you  can  copy 
the  dimensions  into  a  structure  of  type  BITMAP: 

GetObject  (hBitmap,  sizeof  (BITMAP),  (LPSTR)  &bm)  ; 

and  create  a  new  uninitialized  bitmap  of  one-quarter  the  size: 

hBitmap2  =  CreateBitmap  (bm.bmWidth  /  2,  bm.bmHeight  /  2, 

bm.bmPlanes,  bm.bmBits Pixel ,  NULL)  ; 

Now  create  two  memory  device  contexts  and  select  the  original  bitmap  and  the  new  bit¬ 
map  into  them: 

hdcMeml  =  CreateCompatibl eDC  (hdc)  ; 
hdcMem2  =  CreateCompati bl eDC  (hdc)  ; 

SelectObject  (hdcMeml,  hBitmap)  ; 

SelectObject  (hdcMem2,  hBi tmap2 )  ; 

Finally,  copy  the  upper  left  quadrant  of  the  first  bitmap  to  the  second: 

BitBlt  (hdcMem2,  0,  0,  bm.bmWidth  /  2,  bm.bmHeight  /  2, 
hdcMeml,  0,  0,  SRCCOPY)  ; 

You’re  done,  except  for  cleaning  up: 

DeleteDC  (hdcMeml)  ; 

DeleteDC  (hdcMem2)  ; 

DeleteObject  (hBitmap)  ; 

Color  Conversions 

If  the  destination  and  source  device  contexts  in  the  BitBlt  call  have  different  color  charac¬ 
teristics,  Windows  must  convert  the  bitmap  from  one  color  format  to  another.  The  best 
color  conversion  occurs  when  the  source  bitmap  is  monochrome.  Windows  uses  the  text 
color  and  background  color  attributes  in  the  destination  device  context  for  this  conversion: 


Monochrome  DC 

Color  DC 

(Source) 

(Destination ) 

0  (Black) 

Text  color  (default  is  black) 

1  (White) 

Background  color  (default  is  white) 
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The  background  color  attribute,  which  you  encountered  in  Chapter  12,  is  the  color 
Windows  uses  to  fill  in  the  gaps  in  dotted  and  dashed  lines  and  between  the  hatches  in 
hatched  brushes.  You  can  change  the  background  color  with  SetBkColor.  The  text  color, 
which  you’ll  encounter  in  Chapter  14,  determines  the  color  of  text.  You  can  change  this 
with  SetTextColor.  With  default  settings,  the  monochrome  bitmap  simply  turns  into  a 
black-and-white  bitmap  on  the  color  device  context. 

Translating  a  bitmap  in  a  color  source  device  context  to  a  monochrome  destination 
device  context  is  less  satisfactory: 


Color  DC 

Monochrome  DC 

(Source) 

(Destination) 

Pixel  !=  Background  color 

0  (Black) 

Pixel  ==  Background  color 

1  (White) 

In  this  case,  Windows  uses  the  background  color  of  the  source  device  context  to  determine 
what  color  is  translated  to  white.  Every  other  color  is  translated  to  black. 

Here’s  another  color-related  problem:  Windows  needs  to  equate  a  particular  combi¬ 
nation  of  color  bits  in  the  bitmap  (either  in  different  planes  or  in  the  same  plane)  to  the  24- 
bit  color  value  of  the  background  color.  This  means  that  the  color  device  context  must  refer 
to  a  real  device  or  be  a  memory  device  context  based  on  a  real  device.  For  instance,  sup¬ 
pose  you  have  a  monochrome  device  driver.  You  create  a  memory  device  context  based  on 
the  screen  device  context  and  select  a  color  bitmap  into  that  memory  device  context.  You 
now  try  to  transfer  that  bitmap  to  a  monochrome  device  context.  It  won’t  work,  because 
Windows  doesn’t  know  how  the  multiple  planes  or  multiple  bits  per  pixel  in  the  memory 
device  context  bitmap  relate  to  real  colors. 

Mapping  Mode  Conversions 

The  BitBlt  C2.W  requires  different  starting  coordinates  for  the  source  and  destination  device 
contexts,  but  it  needs  only  one  width  and  one  height: 

BitBlt  (hdcDest,  xDest,  yDest,  xWidth,  yHeight, 
hdcSrc,  xSrc,  ySrc,  dwROP)  ; 

The  xWidth  and  yHeight  values  are  in  logical  units,  and  they  apply  to  both  the  rectangle  in 
the  source  device  context  and  the  rectangle  in  the  destination  device  context.  BitBlt  must 
convert  all  coordinates  and  sizes  to  device  coordinates  before  calling  on  the  driver  file  to 
perform  the  actual  operation.  Because  the  xWidth  and  yHeight  values  are  used  for  both  the 
source  and  destination  device  contexts,  the  values  must  be  converted  to  device  units 
(pixels)  separately  for  each  device  context. 

When  the  source  and  destination  device  contexts  are  the  same,  or  when  both  device . 
contexts  use  the  MM -TEXT  mapping  mode,  then  the  size  of  this  rectangle  in  device  units 
will  be  the  same  in  both  device  contexts.  Windows  can  then  do  a  simple  pixel-to -pixel 


639 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


transfer.  However,  when  the  size  of  the  rectangle  in  device  units  is  different  in  the  two 
device  contexts,  Windows  turns  the  job  over  to  the  more  versatile  StretchBlt  function. 

Stretching  Bitmaps  with  StretchBlt 

StretchBlt  adds  two  parameters  to  the  BitBlt  call: 

StretchBlt  (hdcDest,  xDest,  yDest,  xDestWidth,  yDestHeight, 

hdcSrc,  xSrc,  ySrc,  xSrcWidth,  ySrcHeight,  dwROP)  ; 

Because  StretchBlt  accepts  different  width  and  height  parameters  for  the  source  and  desti¬ 
nation  rectangles,  it  allows  you  to  stretch  or  compress  a  bitmap  in  the  source  device  con¬ 
text  to  fit  a  larger  or  smaller  area  in  the  destination  device  context. 

Just  as  BitBlt  provides  a  superset  of  PatBlt's  functionality,  StretchBlt  expands  on 
BitBlt  by  allowing  you  to  specify  the  sizes  of  the  source  and  destination  rectangles  sepa¬ 
rately.  As  with  PatBlt  and  BitBlt ,  all  coordinates  and  values  in  StretchBlt  are  in  logical  units. 
(We’ve  already  used  StretchBlt  in  two  programs:  The  BLOWUP1  program  in  Chapter  4 
used  the  function  to  copy  an  area  of  the  display  into  BLOWUPl’s  client  area;  the 
GRAFMENU  program  in  Chapter  9  used  StretchBlt  to  expand  the  size  of  a  bitmap  for  use  in 
a  menu.) 

StretchBlt  also  allows  you  to  flip  an  image  vertically  or  horizontally.  If  the  signs  of 
xSrcWidth  and  xDestWidth  (when  converted  to  device  units)  are  different,  then  StretchBlt 
creates  a  mirror  image:  Left  becomes  right,  and  right  becomes  left.  If  ySrcHeight  and 
yDestHeight  are  different,  then  Stretch  Bit  turns  the  image  upside  down.  You  can  verify  this 
with  the  BLOWUP1  program  by  capturing  the  image  starting  at  the  upper  right  corner 
(a  negative  width),  the  lower  left  corner  (a  negative  height),  or  the  lower  right  corner  (a 
negative  height  and  width). 

If  you’ve  experimented  with  BLOWUP1,  you’ve  probably  discovered  that  StretchBlt 
can  be  slow,  particularly  when  it  works  with  a  large  bitmap.  StretchBlt  also  has  some  prob¬ 
lems  related  to  the  inherent  difficulties  of  scaling  bitmaps.  When  expanding  a  bitmap, 
StretchBlt  must  duplicate  rows  or  columns  of  pixels.  If  the  expansion  is  not  an  integral 
multiple,  then  the  process  can  result  in  some  distortion  of  the  image. 

When  shrinking  a  bitmap,  StretchBlt  must  combine  two  or  more  rows  or  columns  of 
pixels  into  a  single  row  or  column.  It  does  this  in  one  of  three  ways,  depending  on  the 
stretching  mode  attribute  in  the  device  context.  You  can  use  the  SetStretchBltMode  func¬ 
tion  to  change  this  attribute: 

SetStretchBltMode  (hdc,  nMode)  ; 

The  value  of  nMode  c an  be  one  of  the  following: 

■  BLACKONWHITE  (default) — If  two  or  more  pixels  have  to  be  combined 
into  one  pixel,  StretchBlt  performs  a  logical  AND  operation  on  the  pixels. 

The  resulting  pixel  is  white  only  if  all  the  original  pixels  are  white,  which 
in  practice  means  that  black  pixels  predominate  over  white  pixels. 


640 


Chapter  13:  Bits,  Bits,  and  Metafiles 


■  WHITEONBLACK — If  two  or  more  pixels  have  to  be  combined  into  one 
pixel,  StretchBlt  performs  a  logical  OR  operation.  The  resulting  pixel  is 
black  only  if  all  the  original  pixels  are  black,  which  means  that  white 
pixels  predominate. 

■  COLORONCOLOR — StretchBlt  simply  eliminates  rows  or  columns  of 
pixels  without  doing  any  logical  combination.  This  is  often  the  best 
approach  for  color  bitmaps,  because  the  other  two  modes  can  cause  color 
distortions. 

Animation 

I  mentioned  at  the  beginning  of  Chapter  11  that  GDI  supports  only  static  pictures.  Although 
it’s  true  that  Windows  has  no  traditional  animation  support  (such  as  the  ability  to  flip  video 
pages,  check  for  vertical  retrace  of  the  video  signal,  or  construct  rotatable  sprites),  that 
doesn’t  mean  that  we  can’t  move  images  around  on  the  display.  Yes,  it’s  time  for  the  bounc¬ 
ing  ball  program.  The  BOUNCE  program,  shown  in  Figure  13-3,  constructs  a  ball  that 
bounces  around  in  the  window’s  client  area.  The  program  uses  the  timer  to  pace  the  ball;  it 
draws  the  ball  with  a  simple  “bit-block  transfer”  from  a  memory  device  context. 

BOUNCE.MAK 

#- . - . . 

#  BOUNCE.MAK  make  file 

#- . 

bounce.exe  :  bounce. obj  bounce. def 

$(WINLINK)  bounce,  bounce,  NUL,  $(WINLIB),  bounce 
rc  -t  bounce.exe 

bounce. obj  :  bounce. c 
$ ( WI NCC )  bounce. c 


BOUNCE.C 


/* . - . — 

BOUNCE.C  --  Bouncing  Ball  Program 

(c)  Charles  Petzold,  1992 
- - -  - */ 


^include  <windows.h> 

#define  min(a,b)  (((a)  <  (b))  ?  (a)  :  (b)) 
#define  max(a,b)  (((a)  >  (b))  ?  (a)  :  (b)) 


Figure  13-3.  The  BOUNCE  program. 


(continued) 
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long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "Bounce"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. IpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. lpszMenuName 
wndclass. 1 pszCl assName 


=  CS.HREDRAW  !  CS.VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL.  IDC.ARR0W)  ; 
=  GetStockObject  (WHITE.BRUSH)  ; 
=  NULL  ; 

=  szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "Bouncing  Ball", 

WS_0V ERLAP P EDW I NDOW , 

CW.USEDEFAULT,  CW.USEDEFAULT, 
CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

if  (ISetTimer  (hwnd,  1,  50,  NULL)) 

{ 

MessageBox  (hwnd,  "Too  many  clocks  or  timers!", 

szAppName,  MB_I CON EXC LAMATI ON  !  MB.OK)  ; 
return  FALSE  ; 

} 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 


while  (GetMessage  (&msg,  NULL,  0,  0)) 
{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


{ 


(continued) 
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static  HANDLE  hBitmap  ; 

static  short  cxClient,  cyClient,  xCenter,  yCenter,  cxTotal,  cyTotal f 
cxRadius,  cyRadius,  cxMove,  cyMove,  xPixel,  yPixel  ; 
HBRUSH  hBrush  ; 

HDC  hdc,  hdcMem  ; 

short  nScale  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

xPixel  =  GetDeviceCaps  (hdc,  ASPECTX)  ; 

yPixel  =  GetDeviceCaps  (hdc,  ASPECTY)  ; 

ReleaseDC  (hwnd,  hdc)  ; 
return  0  ; 

case  WM_SIZE  : 

xCenter  =  (cxClient  =  LOWORD  (IParam))  /  2  ; 
yCenter  =  (cyClient  =  HIWORD  (IParam))  /  2  ; 

nScale  =  min  (cxClient  *  xPixel,  cyClient  *  yPixel)  /  16  ; 

cxRadius  =  nScale  /  xPixel  ; 
cyRadius  =  nScale  /  yPixel  ; 

cxMove  =  max  (1,  cxRadius  /  4)  ; 
cyMove  =  max  (1,  cyRadius  /  4)  ; 

cxTotal  =  2  *  (cxRadius  +  cxMove)  ; 
cyTotal  =  2  *  (cyRadius  +  cyMove)  ; 

if  (hBitmap) 

DeleteObject  (hBitmap)  ; 

hdc  =  GetDC  (hwnd)  ; 

hdcMem  =  CreateCompatibleDC  (hdc)  ; 

hBitmap  =  CreateCompatibleBitmap  (hdc,  cxTotal,  cyTotal)  ; 
ReleaseDC  (hwnd,  hdc)  ; 

SelectObject  (hdcMem,  hBitmap)  ; 

Rectangle  (hdcMem,  -1,  -1,  cxTotal  +  1,  cyTotal  +  1)  ; 

hBrush  =  CreateHatchBrush  ( HS_DI AGCROSS .  0L)  ; 

SelectObject  (hdcMem,  hBrush)  ; 

SetBkColor  (hdcMem,  RGB  (255,  0,  255))  ; 

Ellipse  (hdcMem,  cxMove,  cyMove,  cxTotal  -  cxMove, 

cyTotal  -  cyMove)  ; 

DeleteDC  (hdcMem)  ; 

DeleteObject  (hBrush)  ; 
return  0  ; 


(continued) 
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case  WM_TIMER  : 
if  ( ihBitmap) 
break  ; 

hdc  =  GetDC  (hwnd)  ; 

hdcMem  =  CreateCompatibleDC  (hdc)  ; 

SelectObject  (hdcMem,  hBitmap)  ; 

BitBlt  (hdc,  xCenter  -  cxTotal  /  2, 

yCenter  -  cyTotal  /  2,  cxTotal,  cyTotal, 
hdcMem,  0,  0,  SRCCOPY)  ; 

ReleaseDC  (hwnd,  hdc)  ; 

DeleteDC  (hdcMem)  ; 

xCenter  +=  cxMove  ; 
yCenter  +=  cyMove  ; 

if  ((xCenter  +  cxRadius  >=  cxClient)  ! .' 

(xCenter  -  cxRadius  <=  0)) 
cxMove  =  -cxMove  ; 

if  ((yCenter  +  cyRadius  >=  cyClient)  !! 

(yCenter  -  cyRadius  <=  0)) 
cyMove  =  -cyMove  ; 

return  0  ; 

case  WM.DESTROY  : 
if  (hBitmap) 

DeleteObject  (hBitmap)  ; 

KillTimer  (hwnd,  1)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


BOUNCE.DEF 


BOUNCE. DEF  module  definition  file 


NAME  BOUNCE 


(continued) 
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DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 
STACKS I ZE 


'Bouncing  Ball  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


BOUNCE  reconstructs  the  ball  whenever  the  program  gets  a  WM_SIZE  message,  the 
diameter  of  the  ball  being  one-sixteenth  of  either  the  height  or  the  width  of  the  client  area, 
whichever  is  shorter.  However,  the  program  constructs  a  bitmap  that  is  larger  than  the 
ball — on  each  of  its  four  sides,  the  bitmap  extends  beyond  the  ball’s  dimensions  by  one- 
quarter  of  the  ball’s  radius. 

After  the  bitmap  is  selected  into  a  memory  device  context,  it  is  colored  white: 

Rectangle  (hdcMem,  -1,  -1,  xTotal  +  1,  yTotal  +  1)  ; 

A  diagonally  hatched  brush  is  selected  into  the  memory  device  context,  and  the  ball  is 
drawn  in  the  center  of  the  bitmap: 

Ellipse  (hdcMem,  xMove,  yMove,  xTotal  -  xMove,  yTotal  -  yMove)  ; 

The  margins  around  the  edges  of  the  ball  effectively  erase  the  previous  image  of  the  ball 
when  the  ball  is  moved.  Redrawing  the  ball  at  another  position  requires  only  a  simple 
BitBltc all  using  the  ROP  code  of  SRCCOPY: 

BitBlt  (hdc,  xCenter  -  xTotal  /  2, 

yCenter  -  yTotal  /  2,  xTotal,  yTotal, 
hdcMem.  0,  0,  SRCCOPY)  ; 

BOUNCE  demonstrates  the  simplest  way  to  move  an  image  around  the  display,  but 
this  approach  isn’t  satisfactory  for  general  purposes.  If  you’re  interested  in  animation, 
you’ll  want  to  explore  some  of  the  other  ROP  codes  (such  as  SRCINVERT)  that  perform  an 
exclusive  OR  operation  on  the  source  and  destination. 

METAFILES 

A  metafile  is  a  collection  of  GDI  functions  that  are  encoded  in  a  binary  form.  You  create  a 
metafile  by  first  creating  a  metafile  device  context.  You  can  then  use  most  of  the  GDI 
drawing  functions  to  draw  on  this  metafile  device  context.  These  GDI  calls  don’t  really 
draw  on  anything,  however.  Instead,  they  are  stored  within  the  metafile.  When  you  close 
the  metafile  device  context,  you  get  back  a  handle  to  the  metafile.  You  can  then  “play”  this 
metafile  on  a  real  device  context  and  execute  the  GDI  functions  in  the  metafile. 

Metafiles  are  used  most  often  for  sharing  pictures  between  programs  through  the 
clipboard.  Because  metafiles  describe  a  picture  as  a  collection  of  GDI  calls,  they  take  up 
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much  less  space  and  are  more  device  independent  than  bitmaps.  I’ll  begin  the  discussion 
of  metafiles  with  some  simple  examples,  and  then  I’ll  take  up  the  more  theoretical 
considerations. 


Simple  Use  of  Memory  Metafiles 

Suppose  your  company’s  logo  consists  of  a  rectangle  with  lines  drawn  between  the  oppos¬ 
ing  corners  and  a  blue  circle  in  the  center.  You  need  to  draw  this  logo  often  on  the  client 
area  of  your  programs’  windows  and  on  the  printer.  Let’s  make  that  logo  a  metafile. 

We’ll  begin  by  defining  a  few  necessary  variables: 

static  HANDLE  hmf  ; 

HANDLE  hBrush  ; 

HDC  hdcMeta  ; 

During  processing  of  the  WM_CREATE  message,  you  can  create  the  metafile.  You  call 
CreateMetaFile  to  obtain  a  handle  to  a  metafile  device  context: 

hMetaDC  =  CreateMetaFile  (NULL)  ; 

The  NULL  parameter  indicates  that  this  will  be  a  “memory”  metafile;  that  is,  the  metafile 
will  be  stored  in  memory  rather  than  as  a  disk  file. 

You  can  now  draw  your  logo  on  this  metafile  device  context.  You  decide  you  want  it 
to  be  100  units  high  and  100  units  wide: 

Rectangle  (hdcMeta,  0,  0,  100,  100)  ; 

MoveTo  (hdcMeta,  0,  0)  ; 

LineTo  (hdcMeta,  100,  100)  ; 

MoveTo  (hdcMeta,  0,  100)  ; 

LineTo  (hdcMeta,  100,  0)  ; 

hBrush  =  CreateSol idBrush  (RGB  (0,  0,  255))  ; 

SelectObject  (hdcMeta,  hBrush)  ; 

Ellipse  (hdcMeta,  20,  20,  80,  80)  ; 

When  you’ve  finished  drawing,  you  close  the  metafile  device  context  by  calling  Close- 
MetaFile,  which  returns  a  handle  to  the  metafile: 

hmf  =  Cl oseMeta Fi 1 e  (hdcMeta)  ; 

Now  you  can  delete  the  brush  you  created: 

DeleteObject  (hBrush)  ; 

You’re  done  creating  the  metafile.  The  £ra/variable  is  defined  as  static,  so  it  will  remain  in 
existence  during  other  messages. 

You  drew  the  logo  with  a  height  and  width  of  100.  Are  these  logical  units  or  device 
units?  At  this  point,  they  are  neither:  They  are  simply  units.  They  will  take  on  meaning  only 
when  you  play  the  metafile.  Let’s  do  so.  During  processing  of  your  WM -PAINT  message, 
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you  may  want  to  fill  up  the  client  area  with  100  logos,  and  you  don’t  care  whether  they  get 
stretched  out  somewhat.  We’ll  assume  that  you’ve  obtained  values  of  cxClient  and  cyClient, 
representing  the  width  and  height  of  the  client  area  and  that  you’ve  defined  some  of  the 
other  variables  used  in  this  code. 

You  obtain  a  handle  to  the  client-area  device  context  and  set  a  mapping  mode  of 
MM -ANISOTROPIC  with  1000  logical  units  horizontally  and  vertically: 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SetMapMode  (hdc.  MM_AN I SOTROP I C )  ; 

SetWindowExt  (hdc,  1000,  1000)  ; 

SetViewportExt  (hdc,  cxClient,  cyClient)  ; 

Now  you  can  “play  the  metafile”  100  times  by  calling  PlayMetaFile ,  each  time  changing  the 
window  origin  to  move  the  metafile  to  a  new  position: 

for  (x  =  0  ;  x  <  10  ;  x++) 

for  (y  =  0  ;  y  <  10  ;  y++) 

{ 

SetWindowOrg  (hdc,  -100  *  x,  -100  *  y)  ; 

PlayMetaFile  (hdc,  hmf)  ; 

} 

In  calling  PlayMetaFile ,  in  effect  you’re  repeating  all  the  calls  that  you  made  between 
CreateMetaFile  and  CloseMetaFile  when  you  originally  created  the  metafile  during  the 
WM_CREATE  message.  The  results  are  shown  in  Figure  13-4  on  the  following  page. 

When  you’ve  finished  processing,  you  can  end  the  WM-PAINT  message  normally: 

EndPaint  (hwnd,  &ps)  ; 

One  task  remains.  When  you  create  a  metafile,  the  handle  is  really  the  property  of  the  GDI 
module,  and  you  must  explicitly  delete  it  with  DeleteMetaFile  before  you  terminate  the 
program.  You  can  do  this  during  processing  of  the  WM-DESTROY  message: 

case  WM.DESTROY  : 

DeleteMetaFile  (hmf)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

Storing  Metafiles  on  Disk 

In  the  above  example,  the  NULL  parameter  to  CreateMetaFile  meant  that  we  wanted  to 
create  a  metafile  stored  in  memory.  We  can  also  create  a  metafile  stored  on  a  disk  as  a  nor¬ 
mal  file.  This  method  is  preferred  for  large  metafiles  because  it  uses  less  memory  space. 
Windows  has  to  maintain  a  relatively  small  area  in  memory  to  store  the  name  of  the  file 
containing  the  metafile.  On  the  other  hand,  a  metafile  stored  on  disk  requires  a  disk  access 
every  time  you  play  it. 
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Program  Fie  Manager 
Manager 


Figure  13-4.  Multiple  figures  drawn  using  the  PlayMetaFile  function. 

Let’s  use  the  example  of  the  company  logo  again.  In  addition  to  the  variables  shown 
above,  you’ll  need  a  variable  to  store  the  filename  of  the  metafile: 

static  char  szFileName  [80]  ; 

In  this  example,  we’ll  use  a  temporary  file.  During  processing  of  the  WM -CREATE  mes¬ 
sage,  you  can  create  a  filename  for  a  temporary  file  using  the  Windows  GetTempFileName 
function: 

GetTempFileName  (0,  MF,  0,  szFileName)  ; 

Windows  first  checks  the  TEMP  variable  in  the  MS-DOS  environment  to  select  a  disk  and 
subdirectory  for  this  file.  If  there  is  no  TEMP  variable  in  the  MS-DOS  environment,  Win¬ 
dows  uses  the  root  directory  of  the  first  fixed  disk.  The  filename  begins  with  a  tilde  (~)  fol¬ 
lowed  by  the  characters  we’ve  specified  in  the  GetTempFileName  function  (MF)  and  a 
unique  number;  the  extension  is  .TMP.  On  return  from  the  call,  the  filename  is  stored  in  the 
szFileName  array. 

We  create  the  metafile  device  context  using  this  filename: 
hMetaDC  =  CreateMetaFile  (szFileName)  ; 

We  can  write  to  this  device  context  just  as  we  did  in  the  original  example  and  then  close  the 
metafile  device  context  to  get  the  metafile  handle: 

hmf  =  Cl oseMeta File  (hdcMeta)  ; 
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The  processing  of  the  WM -PAINT  message  is  the  same  as  in  the  original  example. 
However,  during  processing  of  the  WM-DESTROY  message,  you’ll  have  to  add  something. 
The  statement: 

DeleteMetaFile  (hmf)  ; 

deletes  the  area  of  memory  that  references  the  metafile  handle  to  the  disk  file,  but  the  disk 
file  still  exists.  You  should  also  delete  that  file  using  the  normal  C  function: 

unlink  (szFileName)  ; 

Here’s  another  way  to  use  disk-based  metafiles.  This  method  doesn’t  require  that  you 
maintain  hmf  as  a  static  variable.  First,  you  get  a  temporary  filename  and  create  the 
metafile  device  context  as  before: 

GetTempFileName  (0,  MF,  0,  szFileName)  ; 
hdcMeta  =  CreateMetaFi le  (szFileName)  ; 

Now  you  draw  on  the  metafile  device  context.  When  you’re  finished,  you  can  close  the 
device  context  and  get  a  handle  to  the  metafile: 

hmf  =  CloseMetaFile  (hdcMeta)  ; 

But  now  you  also  delete  the  metafile: 

DeleteMetaFile  (hmf)  ; 

Do  we  really  want  to  do  this?  We  might.  Deleting  a  disk-based  metafile  invalidates 
the  metafile  handle,  freeing  the  memory  required  for  the  metafile  but  leaving  the  disk  file 
intact.  During  processing  of  the  WM-PAINT  message,  you  can  get  a  metafile  handle  to  this 
disk  file  by  calling  GetMetaFile : 

hmf  =  GetMetaFile  (szFileName)  ; 

Now  you  can  play  this  metafile  just  as  before.  When  processing  of  the  WM-PAINT  message 
is  over,  you  can  delete  the  metafile  handle: 

DeleteMetaFile  (hmf)  ; 

When  it  comes  time  to  process  the  WM -DESTROY  message,  you  don’t  have  to  delete 
the  metafile,  because  it  was  deleted  at  the  end  of  the  WM -CREATE  message  and  at  the  end 
of  each  WM_PAINT  message.  But  you  should  still  delete  the  disk  file: 

unlink  (szFileName)  ; 

Using  Preexisting  Metafiles 

What  we’ve  done  in  the  last  example  above  seems  to  imply  that  we  can  create  a  disk-based 
metafile  in  one  program  and  then  use  it  in  another  program  by  calling  GetMetaFile.  We 
can.  The  MFCREATE  (“metafile  create”)  program,  shown  in  Figure  13-5  beginning 
on  the  following  page,  is  the  shortest  Windows  program  in  this  book.  All  it  does  is  create 
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a  disk-based  metafile  with  the  name  MYLOGO.WMF.  The  .WMF  extension  stands  for  “Win¬ 
dows  metafile”  and  is  the  customary  extension  for  a  metafile  stored  as  a  disk  file. 


MFCREATE.MAK 

# . 

#  MFCREATE.MAK  make  file 

#  . . - 

mfcreate.exe  :  mfcreate.obj  mfcreate.def 

$(WINLINK)  mfcreate,  mfcreate,  NUL,  $(WINLIB),  mfcreate 
rc  -t  mfcreate.exe 

mfcreate.obj  :  mfcreate. c 
$ ( W I NCC )  mfcreate. c 


MFCREATE.C 


/*- . - . 

MFCREATE.C  --  Metafile  Creation  Program 
(c)  Charles  Petzold,  1992 
. */ 


//include  <windows.h> 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HBRUSH  hBrush  =  CreateSol idBrush  (RGB  (0,  0,  255))  ; 
HDC  hdcMeta  =  CreateMetaFi 1 e  ("MYLOGO.WMF")  ; 

Rectangle  (hdcMeta,  0,  0,  100,  100)  ; 

MoveTo  (hdcMeta,  0,  0)  ; 

LineTo  (hdcMeta,  100,  100)  ; 

MoveTo  (hdcMeta,  0,  100)  ; 

LineTo  (hdcMeta,  100,  0)  ; 

SelectObject  (hdcMeta,  hBrush)  ; 

Ellipse  (hdcMeta,  20,  20,  80,  80)  ; 

DeleteMetaFile  ( Cl oseMeta File  (hdcMeta))  ; 

DeleteObject  (hBrush)  ; 

MessageBeep  (0)  ; 

return  FALSE  ; 

} 


Figure  13-5.  The  MFCREATE  program. 
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MFCREATE.DEF 


;  MFCREATE.DEF  module  definition  file 


NAME  MFCREATE 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Metafile  Creation  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


In  the  WinMain  function,  MFCREATE  creates  a  metafile  device  context  using  the 
filename  MYLOGO.WMF: 

hMetaDC  =  CreateMetaFi 1 e  ("MYLOGO.WMF")  ; 

It  then  draws  on  this  device  context.  When  it’s  finished,  it  closes  the  metafile  device  con¬ 
text  and  deletes  the  metafile  handle  in  one  statement: 

DeleteMetaFile  (Cl oseMetaFi 1 e  (hdcMeta))  ; 

The  program  beeps  to  indicate  that  it’s  finished  and  then  exits  WinMain. 

Now  you  can  use  this  metafile  in  another  program.  Here’s  the  entire  WM_PAINT 
logic.  All  you  need  to  obtain  the  handle  to  the  disk-based  metafile  is  GetMetaFile.  After 
you’re  done  with  the  metafile,  you  call  DeleteMetaFile : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SetMapMode  (hdc.  MM_AN I SOTROP I C )  ; 

SetWindowExt  (hdc,  1000,  1000)  ; 

SetViewportExt  (hdc,  xClient,  yClient)  ; 

hmf  =  GetMetaFile  ("MYLOGO.WMF")  ; 

for  (x  =  0  ;  x  <  10  ;  x++) 

for  (y  =  0  ;  y  <  10  ;  y++) 

{ 

SetWindowOrg  (hdc,  -100  *  x,  -100  *  y)  ; 

PlayMetaFile  (hdc,  hmf)  ; 

1 

DeleteMetaFile  (hmf)  ; 

EndPaint  (hwnd,  &ps)  ; 

Alternatively,  you  can  define  &ra/as  a  static  variable  and  call  GetMetaFile  once  during  pro¬ 
cessing  of  WM -CREATE  and  DeleteMetaFile  once  during  processing  of  WM -DESTROY. 
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Of  course,  this  approach  has  some  problems.  The  code  assumes  that  MYLOGO.WMF  is  in 
the  current  directory  or  a  directory  listed  in  the  PATH  environment  variable.  If  the  file  isn’t 
in  the  current  directory  when  you  call  GetMetaFile,  Windows  will  display  a  message  box 
asking  the  user  to  insert  the  MYLOGO.WMF  disk  in  drive  A.  (The  usual  response  of  a  user 
to  a  message  box  of  this  sort  is  “Huh?”)  You  should  search  for  the  file  before  you  call 
GetMetaFile. 

Now  let’s  try  another  approach. 

Using  Metafiles  as  Resources 

In  Chapter  8  you  encountered  a  “user-defined  resource,”  which  in  that  case  was  a  block  of 
text.  Now  let’s  transform  a  metafile  into  a  user-defined  resource.  MYLOGO.WMF  will  then 
become  part  of  the  .EXE  file  for  the  program  that  needs  it.  The  program  MFRESORC 
(“metafile  resource”),  shown  in  Figure  13-6,  accomplishes  this  using  the  MYLOGO.WMF 
metafile  created  by  MFCREATE. 

MFRESORC.MAK 

#- . 

#  MFRESORC.MAK  make  file 
#- . 

mfresorc.exe  :  mfresorc. obj  mfresorc.def  mfresorc. res 

$(WINLINK)  mfresorc,  mfresorc,  NUL,  $(WINLIB),  mfresorc 
rc  -t  mfresorc. res 

mfresorc. obj  :  mfresorc. c 
$(WINCC)  mfresorc. c 

mfresorc. res  :  mfresorc. rc  mylogo.wmf 
$ ( W I NRC )  mfresorc. rc 


MFRESORC.C 

/* 

MFRESORC.C  --  Metafile  Resource  Program 
(c)  Charles  Petzold,  1992 

*/ 

#include  <windows.h> 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


Figure  13-6.  The  MFRESORC  program.  (continued) 
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int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "MFResorc"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

wndclass. cbWndExtra  =  0  ; 

wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  NULL  ; 

wndclass. hCursor  =  LoadCursor  (NULL.  IDC_ARR0W)  ; 

wndclass. hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
wndclass. IpszMenuName  =  NULL  ; 
wndclass. IpszClassName  =  szAppName  ; 

Register'd  ass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Metafile  Resource  Program", 
WS_OVERLAPP EDWIN DOW, 

CWJJSEDEFAULT,  CW_USEDEFAULT, 

CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL.  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HANDLE  hmf  ; 

static  short  cxClient,  cyClient  ; 

HANDLE  hlnstance,  hResource  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 
short  x,  y  ; 


(continued) 
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switch  (message) 

{ 

case  WM.CREATE  : 

hlnstance  =  ( (LPCREATESTRUCT)  IParam)  ->  hlnstance  ; 
hResource  =  LoadResource  (hlnstance, 

FindResource  (hlnstance,  "MyLogo",  "METAFILE")) 

LockResource  (hResource)  ; 

hmf  =  SetMeta Fi 1 eBi ts  (hResource)  ; 

UnlockResource  (hResource)  ; 
return  0  ; 

case  WM.SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HIWORD  (IParam)  ; 
return  0  ; 

case  WM_PA I NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SetMapMode  (hdc,  MM_ANIS0TR0PIC)  ; 

SetWindowExt  (hdc,  1000,  1000)  ; 

SetViewportExt  (hdc,  cxClient,  cyClient)  ; 

for  (x  =  0  ;  x  <  10  ;  x++) 

for  (y  =  0  ;  y  <  10  ;  y++) 

{ 

SetWindowOrg  (hdc,  -100  *  x,  -100  *  y)  ; 
PlayMetaFile  (hdc.  hmf)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

DeleteMetaFile  (hmf)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


MFRESORC.RC 

/* . . . . 

MFRESORC.RC  resource  script 
. */ 

MyLogo  METAFILE  "mylogo.wmf" 
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MFRESORC.DEF 


MFRESORC.DEF  module  definition  file 


NAME  MFRESORC 


DESCRIPTION  'Metafile  Resource  Program  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


The  resource  script  is  only  one  line.  METAFILE  may  look  like  a  normal  resource 
script  keyword  such  as  MENU  or  DIALOG,  but  it  isn’t.  We’re  defining  this  resource  type. 
The  name  we  give  to  this  particular  resource  of  the  METAFILE  type  is  “MyLogo.” 

During  processing  of  the  WM_CREATE  message,  MFRESORC  must  first  call  Find- 
Resource  and  LoadResource  to  obtain  a  handle  to  the  resource: 

hResource  =  LoadResource  ( h I nstance , 

FindResource  (hlnstance,  "MyLogo",  "METAFILE"))  ; 

Then  the  resource  is  locked: 

LockResource  (hResource)  ; 

Normally,  you  would  lock  a  resource  to  obtain  a  pointer  to  the  memory  block.  However, 
LockResource  also  performs  the  chore  of  actually  loading  the  resource  into  memory.  That’s 
all  we  need  to  do.  Now  we  can  convert  this  global  memory  block  to  a  metafile  using 
SetMetaFileBits ,  and  the  resource  can  be  unlocked: 

hmf  =  SetMetaFileBits  (hResource)  ; 

G1 obal Unlock  (hResource)  ; 

SetMetaFileBits  has  a  companion  function,  GetMetaFileBits,  that  converts  a  metafile  handle 
to  a  global  memory  handle.  GetMetaFileBits  can  be  used  only  with  a  memory  metafile. 

The  metafile  that  we  loaded  as  a  resource  is  a  memory  metafile.  If  you’d  prefer  to  use 
a  disk-based  metafile,  you  can  copy  it.  This  is  the  code  you  would  use  following  the 
GlobalUnlock  statement: 

GetTempFileName  (0,  MF,  0,  szFileName)  ; 
hmf2  =  CopyMetaFile  (hmf,  szFileName)  ; 

DeleteMetaFile  (hmf)  ; 
hmf  =  hmf2  ; 
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The  hmf 2  handle  need  not  be  defined  as  a  static  variable.  The  MFRESORC  program  shows 
the  deletion  of  the  metafile  handle  during  processing  of  WM -DESTROY: 

DeleteMetaFile  (hmf)  ; 

You  should  also  delete  the  temporary  file: 

unlink  (szFileName)  ; 

The  CopyMetaFile function  can  also  be  used  to  copy  an  existing  metafile  to  a  memory 
metafile: 

hmf2  =  CopyMetaFile  (hmf,  NULL)  ; 

Looking  at  Metafiles 

You  can  get  a  good  idea  of  what  a  metafile  is  and  is  not  by  dumping  out  the  contents  of 
MYLOGO.WMF.  The  metafile  begins  with  an  18-byte  header  record.  This  is  followed  by  a 
series  of  metafile  records,  each  of  which  contains  three  or  more  2-byte  words.  The  first 
word  is  the  number  of  words  in  the  record,  including  the  first;  the  second  word  is  0;  the 
third  word  is  a  code  that  indicates  the  GDI  call  that  the  record  represents. 

These  codes  are  documented  in  the  Programmer’s  Reference  and  in  WINDOWS.H 
with  identifiers  that  begin  with  the  word  META.  The  low  byte  of  this  word  identifies  the 
particular  GDI  call;  the  high  byte  is  generally  the  number  of  words  that  are  parameters  to 
the  call.  The  words  that  follow  this  code  are  the  actual  parameters  to  the  call  in  reverse 
order,  excluding  the  hdc  parameter.  For  instance,  the  GDI  call: 

Rectangle  (hdcMeta,  0,  0,  100,  100)  ; 

shows  up  in  the  metafile  as  a  seven-word  record.  In  hexadecimal,  these  words  are: 

0007  0000  041B  0064  0064  0000  0000 

The  041B  word  means  that  the  call  is  Rectangle  with  four  parameters,  excluding  the  initial 
hdc.  The  parameters  follow. 

The  only  real  exception  to  this  rule  is  the  SelectObject  call.  Windows  must  save  the 
object  that  the  function  is  selecting  into  the  metafile  device  context.  For  instance,  the  call: 

hBrush  =  CreateSol idBrush  (RGB  (0,  0,  255))  ; 

doesn’t  affect  the  metafile  device  context  at  all.  You  can  even  make  this  call  before  you 
create  the  metafile  device  context  with  CreateMetaFile.  When  you  select  that  brush  into 
the  metafile  device  context,  however,  two  records  must  be  generated.  The  first  is  a  record 
for  CreateBrush Indirect: 

0007  0000  FC02  0000  0000  OOFF  0000 

The  four  words  following  the  identifying  code  FC02  are  the  elements  of  the  LOGBRUSH 
structure  in  the  same  order  (IbStyle  first)  as  the  structure. 
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The  call: 

SelectObject  (hdcMeta,  hBrush)  ; 
is  coded  in  this  record: 

0004  OOOO  012D  0000 

The  single  parameter  0000  indicates  that  it’s  a  handle  to  the  first  object  created  in  the 
metafile.  Any  following  SelectObject  calls  with  other  GDI  objects  will  have  sequentially 
increasing  parameters. 

For  a  memory-based  metafile,  these  records  are  stored  in  a  global  memory  block. 
(You  can  obtain  the  records  using  the  EnumMetaFile  function.)  For  a  disk-based  metafile, 
the  records  are  stored  in  a  disk  file.  The  handle  to  a  disk-based  metafile  references  a  small 
global  memory  block  that  contains  the  drive,  the  directory,  and  the  name  of  the  file. 

Metafile  Dos  and  Don’ts 

When  you  play  the  metafile,  Windows  breaks  down  the  metafile  into  records  and  executes 
the  appropriate  functions  using  the  parameters  in  each  record.  From  the  format  of  the 
metafile  records,  some  facts  should  be  fairly  obvious  (and  some  not  so  obvious). 

The  metafile  device  context  is  not  a  true  device  context.  It  doesn’t  correspond  to  an 
actual  device  or  even  to  a  block  of  memory  such  as  the  memory  device  context.  It’s  simply 
a  repository  for  GDI  calls  that  you  make  using  the  hdcMeta  device  context  handle. 

The  metafile  device  context  doesn’t  have  any  default  device  context  attributes.  It  uses 
whatever  device  context  attributes  are  in  effect  when  you  play  the  metafile. 

All  parameters  enter  the  metafile  device  context  as  numbers.  For  instance,  if  the 
width  and  height  of  your  client  area  are  stored  in  xClient  and  yClient,  and  you  call: 

Rectangle  (hdcMeta,  0,  0,  xClient  /  2,  yClient  /  2)  ; 

then  the  actual  calculated  values  of  xClient  / 2  and  yClient  / 2  will  enter  the  metafile.  If 
you  later  play  back  that  metafile,  it  will  draw  a  rectangle  based  on  these  calculated  values 
regardless  of  the  current  size  of  the  client  area. 

If  you  change  the  mapping  mode  of  your  screen  device  context  before  you  play  the 
metafile,  the  coordinates  in  the  metafile  will  be  interpreted  based  on  the  newly  chosen 
mapping  mode  (unless  the  metafile  itself  changes  the  mapping  mode). 

The  only  calls  that  go  into  the  metafile  are  those  that  take  a  handle  to  a  device  context 
as  the  first  parameter.  Many  GDI  calls  are  not  allowed  in  a  metafile.  It’s  easier  to  say  what 
functions  cannot  be  used  with  a  metafile  device  context,  because  they  fall  into  several 
categories: 

■  Any  function  that  begins  with  the  word  Get ,  including  GetDeviceCaps  and 
GetTextMetrics.  The  metafile  can  do  nothing  with  the  information  that 
these  functions  return. 
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■  Any  other  function  designed  to  return  information  to  the  program: 
RectVisible,  Pt Visible,  EnumFonts,  EnumObjects,  DPtoLP ,  and  LPtoDP. 

The  Escape  function  (which  you’ll  encounter  in  Chapter  16)  is  supported 
only  for  calls  that  don’t  return  data. 

■  Any  function  that  treats  the  metafile  device  context  as  if  it  were  an  actual 
device  context:  ReleaseDC,  DeleteDC,  CreateCompatibleDC \  CreateCom- 
patibleBitmap ,  CreateDiscardableBitmap ,  and  PlayMetaFile. 

■  Some  of  the  more  complex  GDI  functions:  GrayString,  Drawlcon,  and 
SetBrushOrg. 

■  Two  functions  that  require  handles  to  brushes:  FillRect  and  FrameRect. 

As  I  indicated  above,  SelectObject  works  a  little  differently  for  metafile  device  con¬ 
texts.  First,  it  doesn’t  return  the  handle  of  the  object  previously  selected  in  the  device 
context.  When  you  use  SelectObject  with  a  metafile  device  context,  the  function  returns  a 
nonzero  if  it  is  successful  and  0  otherwise.  You  can’t  use  the  construction: 

DeleteObject  (SelectObject  (hdcMeta,  ...));//  WRONG  !!! 

For  SelectObject ,  the  metafile  also  stores  a  description  of  the  logical  object  that  you 
are  selecting  into  the  device  context.  When  you  play  the  metafile,  Windows  starts  with  the 
pen,  brush,  font,  and  region  currently  selected  into  the  device  context.  For  SelectObject 
calls,  Windows  creates  the  indicated  object  and  selects  it  into  the  device  context  but  saves 
the  original  object.  When  it  is  done  playing  the  metafile,  Windows  restores  the  original  ob¬ 
jects  and  deletes  all  the  objects  it  created  to  play  the  metafile. 

When  you  play  a  metafile,  it  uses  the  device  context  attributes  currently  in  effect.  The 
metafile  can  change  any  of  these  attributes,  including  the  mapping  mode,  the  text  color, 
the  drawing  mode,  and  so  forth.  These  changes  remain  in  effect  for  the  device  context  af¬ 
ter  the  metafile  has  finished  playing.  If  you  want  to  retain  your  original  device  context 
attributes  after  the  metafile  has  finished  playing,  call: 

SaveDC  (hdc)  ; 

before  you  play  the  metafile  and: 

RestoreDC  (hdc,  -1)  ; 

after  the  PlayMetaFile  call.  The  metafile  itself  can  also  save  and  restore  the  device  context 
while  it  is  playing.  Each  SaveDC  call  must  be  balanced  by  a  RestoreDC  call  with  a  -1 
parameter. 

One  of  the  purposes  of  metafiles  is  to  provide  a  format  for  device-independent  pic¬ 
tures  that  can  be  shared  by  applications.  There  are  some  other  considerations  involved 
when  using  metafiles  with  the  clipboard  that  will  be  discussed  in  Chapter  16. 
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Text 

and  Fonts 


Displaying  text  on  a  window  was  one  of  the  first  jobs  we  tackled  in  this  book.  Now  it’s  time 
to  explore  the  use  of  different  fonts  and  font  sizes  available  in  Windows  and  to  learn  how  to 
justify  text. 

The  introduction  of  TrueType  in  Windows  3.1  greatly  enhances  the  ability  to  work 
with  text  in  a  flexible  manner.  TrueType  is  a  new  outline  font  technology  that  was  devel¬ 
oped  by  Apple  Computer,  Inc.,  and  Microsoft  Corporation  and  that  will  be  supported  by 
many  font  manufacturers.  Because  TrueType  fonts  are  continuously  scalable  and  can  be 
used  on  both  video  displays  and  printers,  true  WYSIWYG  (what -you-see-is- what -you-get) 
is  now  possible  under  Windows. 

This  chapter  is  largely  restricted  to  writing  text  on  the  video  display  rather  than  to  the 
printer.  The  subject  of  fonts  gets  more  complex  when  you  need  to  write  text  using  the  printer 
because  the  printer  may  be  capable  of  using  a  greater  variety  of  fonts.  Therefore,  the  subject 
of  text  and  fonts  is  continued  in  Chapter  15,  “Using  the  Printer.” 

SIMPLE  TEXT  OUTPUT 

Let’s  begin  by  looking  at  the  different  functions  Windows  provides  for  text  output,  the 
device  context  attributes  that  affect  text,  and  the  use  of  “stock”  fonts. 
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The  Text  Drawing  Functions 

The  most  common  text  output  function  is  the  one  I’ve  used  in  virtually  all  the  sample 
programs: 

TextOut  (hdc,  xStart,  yStart.  IpString,  nCount)  ; 

The  xStart  and  yStart  parameters  are  the  starting  position  of  the  string  in  logical  coordi¬ 
nates.  Normally,  this  is  the  point  at  which  Windows  begins  drawing  the  upper  left  corner  of 
the  first  character.  TextOut  requires  a  far  pointer  to  the  character  string  and  the  length  of 
the  string.  The  function  does  not  recognize  NULL-terminated  character  strings. 

The  meaning  of  the  xStart  and  yStart  parameters  to  TextOut  can  be  altered  by  the 
SetTextAlign  function.  The  TA_LEFT,  TA_RIGHT,  and  TA_CENTER  flags  affect  how 
xStart  is  used  to  position  the  string  horizontally.  The  default  is  TA-LEFT.  If  you  specify 
TA-RIGHT  in  the  SetTextAlign  function,  subsequent  TextOut  calls  position  the  right  side 
of  the  last  character  in  the  string  at  xStart.  For  TA-CENTER,  the  center  of  the  string  is  posi¬ 
tioned  at  xStart. 

Similarly,  the  TA_TOP,  TA_BOTTOM,  and  TA_BASELINE  flags  affect  the  vertical 
positioning.  TA_TOP  is  the  default,  which  means  that  the  string  is  positioned  so  that  yStart 
specifies  the  top  of  the  characters  in  the  string.  Using  TA-BOTTOM  means  that  the  string 
is  positioned  above  yStart.  You  can  use  TA-BASELINE  to  position  a  string  so  that  the  base¬ 
line  is  at  yStart.  The  baseline  is  the  line  below  which  descenders  (such  as  those  on  the 
lowercase  p,  q,  and  y)  hang. 

If  you  call  SetTextAlign  with  the  TA_UPDATECP  flag,  Windows  ignores  the  xStart  and 
yStart  parameters  to  TextO  ut  and  instead  uses  the  current  position  previously  set  by  MoveTo 
or  LineTo.  The  TA-UPDATECP  flag  also  causes  the  TextOut  function  to  update  the  current 
position  to  the  end  of  the  string  (for  TA_LEFT)  or  the  beginning  of  the  string  (for 
TA_RIGHT).  This  is  useful  for  displaying  a  line  of  text  with  multiple  TextOut  calls.  When 
the  horizontal  positioning  is  TA-CENTER,  the  current  position  remains  the  same  after  a 
TextOut  ca\\. 

You’ll  recall  that  displaying  columnar  text  in  the  series  of  SYSMETS  programs  in 
Chapter  2  required  that  one  TextOut  call  be  used  for  each  column.  An  alternative  is  the 
TabbedTextOut  function: 

TabbedTextOut  (hdc,  xStart,  yStart,  IpString,  nCount, 
nNumTabs,  IpnTabStops,  xTabOrigin)  ; 

If  the  text  string  contains  embedded  tab  characters  (‘\t’  or  0x09),  TabbedTextOut  will 
expand  the  tabs  into  spaces  based  on  an  array  of  integers  you  pass  to  the  function. 

The  first  five  parameters  to  TabbedTextOut  are  the  same  as  those  to  TextOut.  The 
sixth  parameter  is  the  number  of  tab  stops,  and  the  seventh  parameter  is  an  array  of  tab 
stops  in  units  of  pixels.  For  example,  if  the  average  character  width  is  8  pixels  and  you  want 
a  tab  stop  every  5  characters,  then  this  array  would  contain  the  numbers  40,  80, 120,  and  so 
forth,  in  ascending  order. 
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If  the  sixth  and  seventh  parameters  are  0  or  NULL,  tab  stops  are  set  at  every  eight 
average  character  widths.  If  the  sixth  parameter  is  1,  the  seventh  parameter  points  to  a 
single  integer,  which  is  repeated  incrementally  for  multiple  tab  stops.  (For  example,  if  the 
sixth  parameter  is  1  and  the  seventh  parameter  points  to  a  variable  containing  the  number 
30,  tab  stops  are  set  at  30,  60,  90,  ...  pixels.)  The  last  parameter  gives  the  logical  x-coordi- 
nate  of  the  starting  position  from  which  tab  stops  are  measured.  This  may  or  may  not  be 
the  same  as  the  starting  position  of  the  string. 

Another  advanced  text  output  function  is  ExtTextOut : 

ExtTextOut  (hdc,  xStart,  yStart,  wOptions,  &rect, 

IpString,  nCount,  1 pxDi stance )  ; 

The  fifth  parameter  is  a  pointer  to  a  rectangle  structure.  This  is  either  a  clipping  rectangle 
(if  wOptions  is  set  to  ETO-CLIPPED)  or  a  background  rectangle  to  be  filled  with  the  cur¬ 
rent  background  color  (if  wOptions  is  set  to  ETO_OPAQUE).  You  can  specify  both  options 
or  neither. 

The  last  parameter  is  an  array  of  integers  that  specify  the  spacing  between  consecu¬ 
tive  characters  in  the  string.  This  allows  a  program  to  tighten  or  loosen  intercharacter  spac¬ 
ing,  which  is  sometimes  required  for  justifying  a  single  word  of  text  in  a  narrow  column. 
The  parameter  can  be  set  to  NULL  for  default  character  spacing. 

A  higher-level  function  for  writing  text  is  DrawText,  which  we  first  encountered  in 
the  HELLOWIN  program  in  Chapter  1.  Rather  than  specifying  a  coordinate  starting  posi¬ 
tion,  you  provide  a  structure  of  type  RECT  that  defines  a  rectangle  in  which  you  want  the 
text  to  appear: 

DrawText  (hdc,  IpString,  nCount,  &rect,  wFormat)  ; 

As  with  the  other  text  output  functions,  DrawText  requires  a  far  pointer  to  the  character 
string  and  the  length  of  the  string.  However,  if  you  use  DrawText  with  NULL-terminated 
strings,  you  can  set  nCount  l o  -1,  and  Windows  will  calculate  the  length  of  the  string. 

When  wFormat  is  set  to  0,  Windows  interprets  the  text  as  a  series  of  lines  that  are 
separated  by  carriage-return  characters  (‘\r’  or  OxOD)  or  linefeed  characters  (‘\n’  or  0x0 A). 
The  text  begins  at  the  upper  left  corner  of  the  rectangle.  A  carriage  return  or  linefeed  is  in¬ 
terpreted  as  a  “newline”  character,  so  Windows  breaks  the  current  line  and  starts  a  new 
one.  The  new  line  begins  at  the  left  side  of  the  rectangle,  spaced  one  character  height 
(without  external  leading)  below  the  previous  line.  Any  text,  including  parts  of  letters,  that 
would  be  displayed  to  the  right  or  below  the  bottom  of  the  rectangle  is  clipped. 

You  can  change  the  default  operation  of  DrawText  by  including  a  wFormat  parame¬ 
ter,  which  consists  of  one  or  more  flags.  The  DT-LEFT  flag  (the  default)  specifies  a  left- 
justified  line,  DT-RIGHT  specifies  a  right-justified  line,  and  DT-CENTER  specifies  a  line 
centered  between  the  left  and  right  sides  of  the  rectangle.  Because  the  value  of  DT-LEFT  is 
0,  you  needn’t  include  the  identifier  if  you  want  text  to  be  left-justified  only. 

If  you  don’t  want  carriage  returns  or  linefeeds  to  be  interpreted  as  newline  charac¬ 
ters,  you  can  include  the  identifier  DT-SINGLELINE.  Windows  then  interprets  carriage 
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returns  and  linefeeds  as  displayable  characters  rather  than  control  characters.  When  using 
DT_SINGLELINE,  you  can  also  specify  whether  the  line  is  to  be  placed  at  the  top  of  the 
rectangle  (DT_TOP,  the  default),  at  the  bottom  of  the  rectangle  (DT_BOTTOM),  or  halfway 
between  the  top  and  bottom  (DT-VCENTER). 

When  displaying  multiple  lines  of  text,  Windows  normally  breaks  the  lines  only  at 
carriage  returns  or  linefeeds.  If  the  lines  are  too  long  to  fit  in  the  rectangle,  however,  you 
can  use  the  DT_WORDBREAK  flag,  which  causes  Windows  to  create  breaks  at  the  end  of 
words  within  lines.  For  both  single-line  and  multiple-line  displays,  Windows  truncates 
any  part  of  the  text  that  falls  outside  the  rectangle.  You  can  override  this  by  including  the 
flag  DT_NOCLIP,  which  also  speeds  up  the  operation  of  the  function.  When  Windows 
spaces  multiple  lines  of  text,  it  normally  uses  the  character  height  without  external  lead¬ 
ing.  If  you  prefer  that  external  leading  be  included  in  the  line  spacing,  use  the  flag  DT- 
_EXTERNALLEADING. 

If  your  text  contains  tab  characters  (‘\t’  or  0x09),  you  need  to  include  the  flag 
DT-EXPANDTABS.  By  default,  the  tab  stops  are  set  at  every  eighth  character  position.  You 
can  specify  a  different  tab  setting  by  using  the  flag  DT_TABSTOP,  in  which  case  the  upper 
byte  of  wFormat  contains  the  character-position  number  of  each  new  tab  stop.  I  recom¬ 
mend  that  you  avoid  using  DT_TABSTOP,  however,  because  the  upper  byte  of  wFormat  is 
also  used  for  some  other  flags. 

Device  Context  Attributes  for  Text 

Several  device  context  attributes  affect  text.  In  the  default  device  context,  the  text  color  is 
black,  but  you  can  change  that  with: 

SetTextColor  (hdc,  rgbColor)  ; 

As  with  pen  colors  and  hatch  brush  colors,  Windows  converts  the  value  of  rgbColor 
to  a  pure  color.  You  can  obtain  the  current  text  color  by  calling  GetTextColor 

The  spaces  between  the  character  strokes  are  colored  in,  based  on  the  setting  of  the 
background  mode  and  the  background  color.  You  can  change  the  background  mode  using: 

SetBkMode  (hdc,  nMode)  ; 

where  nMode  is  either  OPAQUE  or  TRANSPARENT.  The  default  background  mode  is 
OPAQUE,  which  means  that  Windows  uses  the  background  color  to  fill  in  the  area  be¬ 
tween  the  character  strokes.  You  can  change  the  background  color  by  using: 

SetBkColor  (hdc,  rgbColor)  ; 

The  value  of  rgbColor  is  converted  to  that  of  a  pure  color.  The  default  background  color  is 
white.  If  the  background  mode  is  set  to  TRANSPARENT,  Windows  ignores  the  background 
color  and  doesn’t  color  the  area  between  the  character  strokes.  Windows  also  uses  the 
background  mode  and  background  color  to  color  the  spaces  between  dotted  and  dashed 
lines  and  the  area  between  the  hatches  of  hatched  brushes,  as  I  discussed  in  Chapter  12. 
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Many  Windows  programs  specify  WHITE-BRUSH  as  the  brush  that  Windows  uses  to 
erase  the  background  of  a  window.  The  brush  is  specified  in  the  window  class  structure. 
However,  you  may  want  to  make  the  background  of  your  program’s  window  consistent 
with  the  system  colors  that  a  user  can  set  in  the  CONTROL  program.  In  that  case,  you  would 
specify  the  background  color  this  way  in  the  WNDCLASS  structure: 

wndclass.hbrBackground  =  COLOR-WINDOW  +  1  ; 

When  you  want  to  write  text  to  the  client  area,  you  can  then  set  the  text  color  and  back¬ 
ground  color  using  the  current  system  colors: 

SetTextColor  (hdc,  GetSysColor  ( C0L0R_W I NDOWTEXT ) )  ; 

SetBkCol or  (hdc,  GetSysColor  (COLOR-WINDOW))  ; 

If  you  do  this,  you’ll  want  your  program  to  be  alerted  if  the  system  colors  change: 

case  WM-SYSCOLORCHANGE  : 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
break  ; 

Another  device  context  attribute  that  affects  text  is  the  intercharacter  spacing.  By 
default  it’s  set  to  0,  which  means  that  Windows  doesn’t  add  any  space  between  characters. 
You  can  insert  space  by  using  the  function: 

SetTextCharacterExtra  (hdc,  nExtra)  ; 

The  nExtra  parameter  is  in  logical  units.  Windows  converts  it  to  the  nearest  pixel, 
which  can  be  0.  If  you  use  a  negative  value  for  nExtra  (perhaps  in  an  attempt  to  squeeze  char¬ 
acters  closer  together),  Windows  takes  the  absolute  value  of  the  number:  You  can’t  make  the 
value  less  than  0.  You  can  obtain  the  current  intercharacter  spacing  by  calling  GetTextChar- 
acterExtra.  Windows  converts  the  pixel  spacing  to  logical  units  before  returning  the  value. 

Using  Stock  Fonts 

When  you  call  TextOut,  TabbedTextOut,  ExtTextOut,  or  DrawTextxo  write  text,  Windows 
uses  the  font  currently  selected  in  the  device  context.  The  font  defines  a  particular  type¬ 
face  and  a  size.  The  easiest  way  to  display  text  with  various  fonts  is  to  use  the  six  stock  fonts 
that  Windows  provides.  However,  the  range  of  these  is  quite  limited. 

You  can  obtain  a  handle  to  a  stock  font  by  calling: 

hFont  =  GetStockObject  ( n Font )  ; 

where  nFonti s  one  of  the  six  identifiers  discussed  below.  You  can  then  select  that  font  into 
the  device  context: 

SelectObject  (hdc,  hFont)  ; 

Or  you  can  accomplish  this  in  one  step: 

SelectObject  (hdc,  GetStockObject  ( nFont ) )  ; 
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GetStockObject  is  the  same  function  we  used  in  Chapter  12  to  obtain  stock  pens  and 
brushes;  SelectObject  we  used  in  Chapters  12  and  13  to  select  pens,  brushes,  bitmaps,  and 
regions  into  the  device  context. 

The  font  selected  in  the  default  device  context  is  called  the  system  font  and  is  identified 
by  the  GetStockObject  parameter  SYSTEM-FONT.  This  is  the  proportional  ANSI  character 
set  font  that  Windows  uses  for  text  in  menus,  dialog  boxes,  message  boxes,  and  window  cap¬ 
tion  bars.  Specifying  SYSTEM_FIXED_FONT  in  GetStockObject  g ives  you  a  handle  to  a 
fixed-pitch  ANSI  font  compatible  with  the  system  font  used  in  versions  of  Windows  prior  to 
version  3.  I’ve  used  this  font  in  several  sample  programs  in  this  book — when  using  a  fixed- 
pitch  font  was  somewhat  easier  than  using  a  proportional  font.  The  OEM -FIXED -FONT 
identifier  gives  you  a  handle  to  a  font  that  is  often  called  the  terminal  font.  This  is  the  font 
that  Windows  uses  for  windowed  DOS  character-mode  programs.  On  most  devices,  the  ter¬ 
minal  font  is  similar  to  the  fixed-pitch  system  font  but  uses  the  OEM  rather  than  the  ANSI 
character  set.  (The  ANSI  and  OEM  character  sets  are  discussed  in  Chapter  4.) 

The  identifier  ANSI -FIXED -FONT  gives  you  a  handle  to  a  Courier  font  that  is  usually 
smaller  than  the  system  or  terminal  font.  You  can  obtain  a  handle  to  a  font  with  variable  char¬ 
acter  widths  by  using  the  identifier  ANSI  _VAR_FONT.  This  returns  a  handle  to  a  Helvetica  or 
a  Times  Roman  font,  either  of  which  is  usually  smaller  than  the  system  font. 

Finally,  the  identifier  DEVICE -DEFAULT-FONT  is  designed  to  return  a  handle  to  a  font 
that  is  built  into  the  output  device  and  that  is  most  suitable  for  the  device.  For  most  graphics- 
based  video  displays,  no  font  meets  this  condition,  so  the  identifier  returns  a  handle  to  the 
system  font.  For  a  dot-matrix  printer,  however,  this  identifier  returns  a  handle  to  a  font  that 
is  specific  to  the  printer  and  that  in  some  cases  does  not  require  Windows  to  operate  the 
printer  in  a  graphics  mode. 

When  you  select  a  new  font  into  a  device  context,  you  must  calculate  the  font’s  character 
height  and  average  character  width  using  GetTextMetrics.  If  you’ve  selected  a  proportional 
font,  be  aware  that  the  average  character  width  is  really  an  average  and  that  some  characters 
have  a  lesser  or  greater  width.  Later  in  this  chapter  you’ll  learn  how  to  use  GetTextExtent 
to  calculate  the  full  width  of  a  string  made  up  of  variable-width  characters. 

Although  GetStockObject  certainly  offers  the  easiest  access  to  different  fonts,  you  don’t 
have  much  control  over  which  font  Windows  gives  you.  You’ll  see  shortly  how  you  can  be 
very  specific  about  the  typeface  and  size  that  you  want. 

Graying  Character  Strings 

Although  TextOut  and  DrawText  are  the  functions  used  most  often  to  write  character 
strings,  Windows  has  another  text  output  function  called  GrayString  that  exists  for  the  ex¬ 
press  purpose  of  displaying  grayed  text.  Windows  uses  grayed  text  most  often  to  show 
disabled  items  in  menus  and  dialog  boxes.  However,  you  might  also  want  to  use  some 
grayed  text  within  your  client  area.  GrayString  is  complex  and  has  some  limitations.  I’ll 
begin  by  explaining  how  GrayString  generally  works  and  then  show  you  an  easier  way  to 
use  it.  Here’s  the  general  syntax: 
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GrayString  (hdc,  hBrush,  lpfnOutputFunction,  dwData, 
nCount,  xStart,  yStart,  xWidth,  yHeight)  ; 

GrayString  uses  a  call-back  function  of  the  form: 

BOOL  FAR  PASCAL  .export  OutputFuncti on  (HDC  hdc,  DWORD  dwData, 

short  nCount) 

{ 

[other program  lines] 
return  1  ; 

} 


You  must  obtain  a  far  pointer  to  the  function  by  calling  MakeProcInstance : 

lpfnOutputFunction  =  MakeProcInstance  (hlnstance,  OutputFunction)  ; 

This  far  pointer  is  the  third  parameter  to  GrayString.  The  dwData  and  nCount  parameters 
to  GrayString  are  simply  passed  as  parameters  to  this  call-back  function.  Most  often, 
dwData  is  a  far  pointer  (converted  to  a  doubleword)  to  the  text  you  want  to  gray,  and 
nCount  is  set  to  the  number  of  characters. 

Here’s  what  happens  when  you  call  GrayString :  Windows  creates  a  memory  device 
context  and  a  monochrome  bitmap  using  the  xWidth  and  yHeight  parameters  to  Gray¬ 
String.  It  selects  the  bitmap  into  the  memory  device  context  and  passes  to  the  call-back 
function  the  memory  device  context  handle,  the  dwData  parameter,  and  the  nCount 
parameter. 

Within  the  call-back  function,  you  draw  on  this  memory  device  context.  The  text 
color  has  been  set  to  black  and  the  background  color  to  white.  The  drawing  you  do  is  rela¬ 
tive  to  the  upper  left  corner  of  this  memory  device  context  rather  than  the  upper  left  corner 
of  your  original  device  context.  The  output  function  returns  a  1  if  all  goes  well.  Windows 
then  uses  the  PatBlt  function  to  perform  a  bitwise  OR  operation  on  this  memory  device 
context  using  a  brush  containing  half  black  pixels  and  half  white  pixels.  (The  ROP  code  is 
0xFA0089.)  As  a  result,  the  white  pixels  in  the  memory  device  context  are  unchanged,  and 
half  the  black  pixels  become  white  pixels. 

Windows  then  performs  a  BitBlt  operation  from  this  memory  device  context  to  the 
device  context  you  specified  in  the  GrayString  call  (probably  your  client-area  device  con¬ 
text),  starting  at  the  point  ( xStart ,  yStarf).  The  ROP  code  is  0xB8074A,  which  corresponds 
to  a  Boolean  operation  of: 

((Destination  a  Pattern)  &  Source)  a  Pattern 

You  may  recall  this  particular  ROP  code  from  Chapter  13.  The  pixels  in  your  original  device 
context  (the  destination)  that  correspond  to  white  pixels  in  the  memory  device  context 
(the  source)  are  unchanged.  The  pixels  in  your  original  device  context  that  correspond  to 
black  pixels  in  the  memory  device  context  are  colored  with  the  brush  specified  in  the 
GrayString  call.  In  other  words,  every  other  pixel  that  you  color  black  in  the  memory  de¬ 
vice  context  is  colored  with  the  brush  in  your  original  device  context. 
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The  GrayString  function  has  certain  limitations.  Here  are  the  most  important  ones: 

■  GrayString  requires  the  MM -TEXT  mapping  mode.  This  is  because  the 
xWidth  and  yHeight  parameters  to  GrayString  are  treated  as  device  units 
when  Windows  creates  the  bitmap,  but  they  are  treated  as  logical  units 
when  PatBlt  and  BitBlt  are  called. 

■  The  memory  device  context  has  default  device  context  attributes  when 
Windows  calls  the  output  function.  Therefore,  if  you’ve  selected  a  non¬ 
default  font  into  your  device  context  before  calling  GrayString, ,  this  font 
will  not  be  selected  in  the  memory  device  context.  You  can,  however,  select 
the  same  font  into  the  memory  device  context  within  the  output  function. 

■  Normally,  the  dwData  parameter  points  to  a  character  string,  and  nCount 
is  the  number  of  characters;  but  dwData  and  nCount  can  really  be  any¬ 
thing  you  want.  Be  aware  of  the  following: 

□  If  nCount  is  0,  Windows  assumes  that  dwData  is  a  character  string  and 
calculates  the  number  of  characters.  That  calculated  value  is  passed  to 
the  call-back  function. 

□  If  you  specify  an  xWidth  or  a  yHeight  value  of  0,  Windows  computes 
the  width  and  height  of  the  string  pointed  to  by  dwData.  It  uses  the 
memory  device  context  for  this  calculation,  so  these  widths  and 
heights  are  based  on  the  width  and  height  of  the  system  font,  regard¬ 
less  of  the  font  you  eventually  use  in  the  call-back  function. 

□  If  the  output  function  returns  0,  then  Windows  assumes  that  an  error 
has  occurred  and  doesn’t  draw  anything  on  your  original  device 
context.  However,  if  you  set  the  nCount  parameter  to  -1  and  the  output 
function  returns  0,  then  Windows  simply  transfers  the  memory  device 
context  intact  to  your  original  device  context  without  first  graying  it. 

In  this  case,  you  have  to  determine  the  number  of  characters  in  the 
character  string  yourself,  within  the  call-back  function. 

If  you  have  a  good  feel  for  bitmaps,  memory  device  contexts,  and  the  raster  operations,  you 
might  want  to  sidestep  these  limitations  by  writing  your  own  text-graying  function.  Or  you 
might  prefer  to  use  the  easy  GrayString  syntax  presented  below. 

The  Easy  Use  of  GrayString 

In  the  general  syntax  of  GrayString, ,  the  parameter  called  IpfnOutputFunction  is  a  long 
pointer  to  a  call-back  function.  If  you  set  that  parameter  to  NULL,  Windows  uses  the  Text- 
Out  function.  You  can  also  set  the  xWidth  and  yHeight  parameters  to  0.  Here’s  the  syntax 
you’ll  want  to  use  for  writing  grayed  text  to  the  display: 
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GrayString  (hdc,  GetStockObject  (BLACK_BRUSH) ,  NULL, 

(DWORD)  IpString,  nCount,  xStart,  yStart,  0,  0)  ; 

If  IpString  is  a  pointer  to  a  NULL-terminated  text  string,  then  nCount  can  also  be  set 
to  0,  and  Windows  will  calculate  the  length.  GrayString  uses  the  system  font  regardless  of 
the  font  currently  selected  in  the  device  context.  The  function  ignores  the  device  context 
settings  for  the  text  color,  background  mode,  and  background  color,  and  it  requires  the 
MM _TEXT  mapping  mode. 

On  color  displays,  you  can  also  pass  to  GrayString  a  brush  handle  from  CreateSolid- 
Brush ,  if  you’ve  created  a  brush  of  a  pure  color.  On  monochrome  displays,  however,  this 
brush  would  become  a  black-and-white  dithered  brush,  and  you  would  encounter  the 
same  problems  as  with  a  gray  brush. 

Gray  Strings  Without  GrayString 

In  versions  of  Windows  prior  to  3,  the  display  drivers  for  the  EGA  and  VGA  supported  only 
eight  pure  colors  (black,  red,  green,  blue,  yellow,  magenta,  cyan,  and  white)  on  color  dis¬ 
plays.  Grays  had  to  be  simulated  using  a  dithered  pattern  of  black  and  white  pixels. 

Beginning  in  Windows  3,  the  EGA  and  VGA  display  drivers  support  16  colors,  in¬ 
cluding  two  gray  shades.  This  means  that  you  can  display  gray  text  without  using  the  Gray¬ 
String  function. 

To  do  this,  first  call  GetSysColor  with  a  parameter  of  COLOR-GRAYTEXT: 

rgbGrayText  =  GetSysColor  (C0L0R_GRAYTEXT)  ; 

If  rgbGrayText  is  equal  to  0L,  then  your  program  should  use  the  GrayString  function 
to  draw  a  grayed  string.  Otherwise,  you  can  simply  set  the  text  color  to  rgbGrayText'. 

SetTextColor  (hdc,  rgbGrayText)  ; 


BACKGROUND  ON  FONTS 

Much  of  the  remainder  of  this  chapter  addresses  working  with  different  fonts.  Before  you 
get  involved  with  specific  code,  however,  you’ll  benefit  from  having  a  firm  grasp  of  the 
basics  of  fonts  as  they  are  implemented  in  Windows  3.1. 

The  Types  of  Fonts 

Windows  supports  two  broad  categories  of  fonts,  called  “GDI  fonts”  and  “device  fonts.” 

The  GDI  fonts  are  stored  in  files  on  your  hard  disk;  those  that  come  with  Windows  are 
stored  in  the  SYSTEM  subdirectory  of  your  Windows  directory. 

Many  of  these  GDI  font  files,  which  are  sometimes  called  “font  resource  files,”  have 
the  extension  .FON.  Each  file  contains  one  or  more  complete  fonts.  These  files  are  in  the 
New  Executable  format,  which  you  can  verify  by  running  Microsoft’s  EXEHDR  or  Borland’s 
TDUMP  on  them.  They  are  library  modules,  although  somewhat  unusual  ones  in  that  they 
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contain  no  code  or  data.  All  they  contain  are  two  types  of  resources:  a  font  directory  and 
the  fonts  themselves. 

TrueType  fonts  are  also  GDI  fonts.  They  are  stored  in  files  with  the  extension  .TTF. 
These  files  are  not  in  the  New  Executable  format.  However,  for  each  .TTF  file  there  is  a 
small  .FOT  file,  which  is  a  resource-only  New  Executable  file  that  contains  a  font  directory 
that  references  the  corresponding  .TTF  file. 

The  second  broad  category  of  fonts,  the  device  fonts,  are  internal  to  particular 
graphics  output  devices.  For  video  display  adapters,  device  fonts  are  currently  rare.  Win¬ 
dows  uses  the  video  adapter  in  graphics  mode,  so  it  must  use  the  GDI  fonts  and  write  the 
pixels  directly  to  the  video  display. 

For  printers,  however,  device  fonts  are  very  common.  For  instance,  Windows  can 
write  text  to  a  dot-matrix  printer  using  either  the  printer’s  normal  text  mode  or  the  printer’s 
graphics  mode.  In  text  mode,  Windows  uses  a  device  font  and  needs  to  send  only  the  ASCII 
numbers  of  the  characters  out  to  the  printer.  In  graphics  mode,  Windows  can  use  a  GDI 
font  and  must  send  the  pixel  patterns  to  the  printer.  For  laser  printers,  device  fonts  can  be 
stored  in  ROM  within  the  printer  or  in  ROM  cartridges.  If  the  printer  requires  a  download¬ 
able  font  that  originates  from  a  disk  file,  this  font  is  also  classified  as  a  device  font  because 
it  is  specific  to  the  particular  device. 

GDI  fonts  come  in  three  flavors — raster  fonts,  stroke  fonts,  and  TrueType  fonts. 

A  raster  font  is  sometimes  called  a  bitmap  font,  because  in  a  raster  font  file,  each 
character  is  stored  as  a  bitmap  pixel  pattern.  Figure  14-1  shows  a  character  from  a  GDI 
raster  font,  enlarged  so  that  you  can  see  the  individual  pixels. 


Figure  14-1 .  A  GDI  raster  font  character. 

Each  raster  font  is  designed  for  a  specific  aspect  ratio  and  character  size.  Windows 
can  create  larger  character  sizes  from  GDI  raster  fonts  by  simply  duplicating  rows  or  col¬ 
umns  of  pixels.  However,  this  can  be  done  only  in  integral  multiples  and  within  certain 
limits.  Right  away,  you  can  probably  perceive  one  major  difference  between  drawing  other 
graphics  on  the  display  and  writing  text  to  the  display  using  the  GDI  raster  fonts.  Although 
you  can  draw  a  rectangle  of  virtually  any  size,  GDI  raster  fonts  are  available  only  in 
discrete  sizes.  (You  can’t  write  text  using  a  raster  font  smaller  than  the  smallest  raster  font. 
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If  you  want  a  GDI  raster  font  of  a  specific  size,  that  size  may  not  be  available.)  For  this 
reason,  GDI  raster  fonts  are  termed  “nonscalable”  fonts.  They  cannot  be  expanded  or  com¬ 
pressed  to  an  arbitrary  size.  The  primary  advantages  of  raster  fonts  are  performance  (be¬ 
cause  they  are  very  fast  to  display)  and  readability  (because  they  have  been  hand-designed 
to  be  as  legible  as  possible). 

Prior  to  Windows  3.1,  the  only  other  GDI  fonts  supplied  with  Windows  were  the  GDI 
stroke  fonts.  The  stroke  fonts  are  defined  as  a  series  of  line  segments  in  a  “connect-the- 
dots”  format.  Stroke  fonts  are  continuously  scalable,  which  means  that  the  same  font  can  be 
used  for  graphics  output  devices  of  any  resolution,  and  the  fonts  can  be  increased  or 
decreased  to  any  size.  However,  performance  is  poor,  legibility  suffers  greatly  at  small 
sizes,  and  at  large  sizes  the  characters  look  decidedly  weak  because  their  strokes  are  single 
lines.  Figure  14-2  shows  a  character  from  a  blown-up  GDI  stroke  font. 


Figure  14-2.  A  GDI  stroke  font  character. 

Stroke  fonts  are  now  sometimes  called  “plotter  fonts”  because  they  are  particularly 
suitable  for  plotters  but  not  for  anything  else. 

For  both  GDI  raster  fonts  and  GDI  stroke  fonts,  Windows  can  “synthesize”  boldface, 
italics,  underlining,  and  strikethroughs  without  storing  separate  fonts  for  each  attribute.  For 
italics,  for  instance,  Windows  simply  shifts  the  upper  part  of  the  character  to  the  right. 

With  Windows  3.1,  modern  outline  font  technology  comes  to  Windows  in  the  form  of 
TrueType.  A  TrueType  font  uses  straight  lines  and  curves  to  define  the  outline  of  each  char¬ 
acter.  These  lines  and  curves  are  stored  based  on  an  arbitrary  coordinate  system.  By  simply 
scaling  these  coordinates,  TrueType  fonts  can  be  continuously  scaled  and  even  rotated. 

When  your  program  wants  to  use  a  TrueType  font  of  a  particular  size,  Windows 
“rasterizes”  the  font.  This  means  that  Windows  scales  the  coordinates  connecting  the  lines 
and  curves  of  each  character  using  “hints”  that  are  included  in  the  TrueType  font  file. 

These  hints  compensate  for  rounding  errors  that  would  otherwise  cause  a  resultant 
character  to  be  unsightly.  (For  example,  in  some  fonts  the  two  legs  of  a  capital  H  should  be 
the  same  width.  A  blind  scaling  of  the  font  could  result  in  one  leg  being  a  pixel  wider  than 
the  other.  The  hints  prevent  this  from  happening.)  The  resultant  outline  of  each  character 
is  then  used  to  create  a  bitmap  of  the  character.  These  bitmaps  are  cached  in  memory  for 
future  use. 
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Obviously,  the  rasterization  of  a  TrueType  font  takes  some  time.  However,  once  a 
TrueType  font  of  a  particular  size  has  been  rasterized  and  cached  in  memory,  performance 
is  as  fast  as  using  the  GDI  raster  fonts. 

Although  the  legibility  of  TrueType  fonts  is  very  good,  they  are  not  quite  as  readable 
as  the  hand-tuned  raster  fonts.  However,  italic  and  boldface  versions  of  TrueType  fonts  are 
not  synthesized  as  they  are  in  the  GDI  raster  fonts  and  GDI  stroke  fonts.  Instead,  separate 
TrueType  font  files  provide  italic  and  boldface  versions.  This  is  preferable  because  the 
italic  versions  of  some  fonts  are  quite  different  from  the  nonitalic  versions. 

The  following  table  summarizes  the  characteristics  of  the  GDI  raster,  TrueType,  and 
stroke  fonts: 


GDI  Font 

Performance 

Appearance 

Scalable 

Raster 

The  best 

The  best 

Hardly 

TrueType 

Almost  as  good  as  raster 

Almost  as  good  as  raster 

Yes 

Stroke 

Poor 

Poor 

Yes 

The  GDI  stroke  fonts  should  be  avoided  except  for  use  on  plotters.  For  all  but  the 
most  rudimentary  applications  involving  fonts,  the  scalability  of  TrueType  fonts  greatly 
outweighs  any  disadvantages  when  compared  with  the  GDI  raster  fonts.  Because  the 
TrueType  fonts  can  be  used  on  any  type  of  graphics  output  device  (except  plotters),  true 
WYSIWYG  is  possible.  In  the  past,  programs  had  to  approximate  printer  output  by  using 
the  GDI  raster  fonts.  Now,  TrueType  fonts  can  be  used  on  both  devices. 

Because  device  fonts  are  stored  in  printers  and  used  in  a  device-specific  manner,  it  is 
impossible  to  discuss  them  in  the  same  detail  as  GDI  fonts.  Many  modern  laser  printers  (in 
particular,  PostScript  printers)  support  their  own  outline  font  technologies.  Sometimes  the 
device  can  italicize  or  boldface  a  device  font,  and  sometimes  it  can’t.  You  can  obtain  such 
information  from  the  GetDeviceCaps  function  using  the  TEXTCAPS  index.  If  you  want  to 
obtain  this  information  for  particular  printers,  you  can  use  the  GetDeviceCaps  function  as 
shown  in  the  DEVCAPS1  program  in  Chapter  11. 

Type  Talk  I:  Families  and  Faces 

I’ve  been  using  the  word  font  rather  loosely  until  now.  The  more  rigorous  definition  of  font 
that  is  preferred  by  typographers  is  this:  A  font  is  a  complete  collection  of  characters  of  a 
particular  typeface  and  a  particular  size. 

To  a  typographer,  the  term  typeface  denotes  not  only  the  style  of  type  (such  as 
Courier  or  Helvetica)  but  also  the  size  of  type  and  whether  the  characters  are  oblique  or 
italic  or  boldface,  for  example.  When  working  with  Windows,  we’ll  use  the  word  “typeface” 
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to  denote  simply  the  style  of  the  type.  Common  typefaces,  in  addition  to  Courier  and 
Helvetica,  are  Times  Roman,  Gothic,  and  Palatino. 

Windows  groups  typefaces  into  five  “families,”  based  on  the  general  appearance  of 
the  type.  These  families  are  called  Modern,  Swiss,  Roman,  Script,  and  Decorative.  The 
most  common  typefaces  are  categorized  as  Modern,  Swiss,  or  Roman,  depending  on  two 
characteristics. 

The  first  characteristic  involves  “stroke  width” — the  width  of  the  lines  that  make  up 
the  characters — which  can  be  constant  or  variable.  Typefaces  in  the  Modern  family  have 
constant  stroke  widths.  Typefaces  in  the  Swiss  and  Roman  families  have  variable  stroke 
widths.  (Most  typefaces  with  constant  stroke  widths  are  also  of  “fixed  pitch,”  which  means 
that  all  the  characters  in  the  font  are  the  same  width.  Typefaces  with  variable  stroke  widths 
are  generally  of  “variable  pitch,”  which  means  that  the  characters  have  variable  widths. 
However,  it  is  the  stroke  width  rather  than  the  use  of  fixed  or  variable  pitch  that  determines 
the  family  of  a  particular  typeface.) 

The  second  characteristic  involves  “serifs,”  which  are  small  lines  that  finish  off  the 
character  strokes.  The  Swiss  family  comprises  “sans  serif”  typefaces  (typefaces  with  no 
serifs);  the  Roman  family  comprises  serif  typefaces. 

The  Script  family  comprises  typefaces  that  resemble  cursive  handwriting.  The 
Decorative  family  includes  typefaces  of  elaborate  design  (such  as  Old  English).  At  one 
time,  symbol  fonts  were  considered  to  be  in  the  Decorative  family,  but  they  are  now  gener¬ 
ally  identified  as  symbol  fonts  by  a  character-set  attribute  of  the  font — the  character  set  is 
Symbol  rather  than  ANSI  or  OEM. 

The  following  table  summarizes  the  grouping  of  typefaces  into  families  and  shows 
the  identifiers  (defined  in  WINDOWS. H)  that  programs  can  use  to  specify  the  font  family: 


Font  Family 

Stroke 

Usual  Pitch 

Serifs 

Typical  Typefaces 

FF-MODERN 

Fixed 

Fixed 

— 

Courier,  Elite,  Pica 

FF-SWISS 

Variable 

Variable 

No 

Helvetica,  Avant  Garde 

FF-ROMAN 

Variable 

Variable 

Yes 

Times  Roman,  Palatino, 
New  Century  Schoolbook 

FF-SCRIPT 

— 

— 

— 

Cursive,  Zapf  Chancery 

FF-DECORATIVE 

— 

— 

— 

Old  English 

WINDOWS.H  also  includes  a  sixth  font-family  identifier,  FF-DONTCARE,  which  a  pro¬ 
gram  can  use  when  it  wants  to  select  a  font  but  doesn’t  care  what  family  it  comes  from. 

Interestingly  enough,  typeface  names  can  be  copyrighted,  but  font  designs  cannot. 
So  that  Microsoft  can  avoid  paying  license  fees  to  use  copyrighted  font  names,  the  fonts  that 
come  with  Windows  are  cloned  from  other  fonts  and  given  names  other  than  those  by 
which  the  font  might  be  known  to  a  typographer. 
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It  will  be  helpful  to  become  familiar  with  the  fonts  that  come  with  Windows,  so  let’s 
take  a  look  at  them. 

Windows  comes  with  three  stroke  fonts,  which  are  given  the  typeface  names  shown 
in  Figure  14-3. 


Program  File  Manager 
Manager 


Figure  1 4-3.  Windows  stroke  font  typefaces  for  the  video  display. 

As  you  can  see,  these  typeface  names  are  actually  three  of  the  font-family  names  shown  in 
the  table  on  the  preceding  page.  The  stroke  fonts  are  always  OEM  character-set  fonts. 

Windows  comes  with  several  raster  fonts,  four  of  which  have  the  typeface  names 
shown  in  Figure  14-4. 

Prior  to  Windows  3.1,  the  MS  Serif  font  was  known  as  Tms  Rmn,  which  (as  you  can 
probably  guess)  means  that  it’s  a  Times  Roman  clone.  You  can  use  either  name  in  your 
program  to  refer  to  this  font.  Prior  to  Windows  3.1,  the  MS  Sans  Serif  font  was  known  as 
Helv.  The  last  font  shown  in  Figure  14-4  has  the  typeface  name  Symbol. 

Windows  also  comes  with  raster  fonts  with  four  other  typeface  names — System  is  the 
system  font,  FixedSys  is  the  fixed-pitch  system  font,  Terminal  is  the  fixed-pitch  OEM  font, 
and  Small  Fonts  is  a  Roman  family  font  in  small  sizes  (as  I’ll  discuss  later  in  this  chapter). 
With  the  exception  of  Symbol  and  Terminal,  all  these  raster  fonts  use  the  ANSI  character 
set.  The  Symbol  font  uses  the  Symbol  character  set  and  the  Terminal  font  uses  the  OEM 
character  set. 

The  TrueType  typefaces  are  shown  in  Figure  14-5. 
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11  E°nts _ 

Courier  AaBbCcDdEe 

MS  Serif  AaBbCcDdEe 

MS  Sans  Serif  AaBbCcDdEe 

Ti///x/3oX  AaBSXxAdEf 

Program  Fie  M  anager 
Manager 


Figure  1 4-4.  Windows  raster  font  typefaces  for  the  video  display. 


FontShow 


Fonts 


Courier  New  AaBbCcDdEe 

Courier  New  Bold  AaBbCcDdEe 
Courier  New  Italic  AaBbCcDdEe 

Courier  New  Bold  Italic  AaBbCcDdEe 

Times  New  Roman  AaBbCcDdEe 

Times  New  Roman  Bold  AaBbCcDdEe 

Times  New  Roman  Italic  AaBbCcDdEe 

Times  New  Roman  Bold  Italic  AaBbCcDdEe 

Arial  AaBbCcDdEe 

Arial  Bold  AaBbCcDdEe 

Arial  Italic  AaBbCcDdEe 

Arial  Bold  Italic  AaBbCcDdEe 

Exf/tiRoX  AaB/3XxA6E s 


I _ _ 

Program  Fie  Manager 
Manager 


Figure  1 4-5.  Windows  TrueType  typefaces  for  the  video  display. 
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The  Courier  New  font  is  a  Courier  clone,  Times  New  Roman  is  a  Times  Roman  clone, 
and  Arial  is  a  Helvetica  clone.  All  these  fonts  use  the  ANSI  character  set  with  the  exception 
of  the  last  two  fonts  shown  in  Figure  14-5,  which  are  called  Symbol  and  Wingdings  and 
which  use  the  Symbol  character  set. 

As  you’ll  see,  Windows  provides  functions  for  programs  to  determine  the  names  of 
the  typefaces  available  on  a  particular  device.  These  functions  become  particularly  impor¬ 
tant  when  the  device  is  a  printer  because  printers  can  include  many  device  fonts  with 
names  that  can  be  determined  only  when  the  program  interrogates  the  device. 

The  Font  Resource  Files 

The  SYSTEM  subdirectory  of  the  Windows  directory  contains  several  files  with  the  exten¬ 
sion  .FON.  Some  of  the  filenames  begin  with  the  letters  COUR  (Courier),  SSERIF  (MS  Sans 
Serif),  SERIF  (MS  Serif)  and  SYMBOL  (Symbol)  followed  by  another  letter — A,  B,  C,  D,  E, 
or  F;  these  are  the  font  resource  files  containing  the  GDI  raster  fonts.  Each  font  resource  file 
contains  one  or  more  sizes  of  a  particular  typeface.  The  terminating  letter  indicates  the 
resolution  and  aspect  ratio  for  which  the  font  was  designed. 

The  GDI  stroke  fonts  are  stored  in  the  MODERN.FON,  ROMAN.FON,  and 
SCRIPT.FON  files.  Because  the  GDI  stroke  fonts  are  continuously  scalable,  they  aren’t 
based  on  a  particular  aspect  ratio  or  device  resolution. 

The  system  and  terminal  fonts  are  stored  in  files  that  begin  with  the  name  of  the  de¬ 
vice  for  which  they  have  been  designed  (such  as  CGA,  EGA,  VGA,  and  8514)  and  that  end 
with  the  terms  SYS  (proportional  system  font),  FIX  (fixed-pitch  system  font),  and  OEM 
(terminal  font). 

The  following  table  lists  the  GDI  font  resource  files  for  the  raster  and  stroke  fonts,  the 
font-family  identifiers,  the  typefaces,  and  the  character  sets: 


Filename 

Type 

Family 

Typeface 

Character  Set 

_ SYS. FON 

Raster 

FF-SWISS 

System 

ANSI 

_ FIX. FON 

Raster 

FF-DONTCARE 

FixedSys 

ANSI 

_ OEM. FON 

Raster 

FF-MODERN 

Terminal 

OEM 

COURx.FON 

Raster 

FF-MODERN 

Courier 

ANSI 

SSERIFx.FON 

Raster 

FF-SWISS 

MS  Sans  Serif 

ANSI 

SERIFx.FON 

Raster 

FF-ROMAN 

MS  Serif 

ANSI 

SYMBOLx.FON 

Raster 

FF-DECORATIVE 

Roman 

Symbol 

SMALLx.FON 

Raster 

FF-ROMAN 

Small  Fonts 

ANSI 

MODERN.FON 

Stroke 

FF-MODERN 

Modern 

OEM 

ROMAN.FON 

Stroke 

FF_ROMAN 

Roman 

OEM 

SCRIPT.FON 

Stroke 

FF-SCRIPT 

Script 

OEM 

674 


Chapter  14:  Text  and  Fonts 


The  GDI  stroke  font  files  are  sometimes  referred  to  as  “Set  #1.”  There  are  six  other 
sets  that  correspond  to  the  terminating  letter  of  the  COURx.FON,  SSERIFx.FON, 
SERIFx.FON,  SYMBOLx.FON,  and  SMALLx.FON  filenames: 


Set 

Letter 

Pixels  per  Logical  Inch 
Aspect  Ratio  X  (Horz)  Y  (Vert) 

Device 

# 2 

A 

200 

96 

48 

CGA 

#3 

B 

133 

96 

72 

EGA 

#4 

C 

83 

60 

72 

Okidata  printers 

#5 

D 

167 

120 

72 

IBM,  Epson  printers 

#6 

E 

100 

96 

96 

VGA 

#7 

F 

100 

120 

120 

8514 

Depending  on  what  printers  you’ve  installed  and  whether  you’ve  used  the  Windows 
Setup  program  to  change  the  video  display  driver,  some  of  these  files  may  or  may  not  be 
present  on  your  hard  disk.  Also,  some  users  may  have  other  Windows  raster  font  files 
present. 

The  aspect  ratio  in  the  above  table  is  calculated  as: 

10Q  *  horizontal  pixels  per  logical  inch 
vertical  pixels  per  logical  inch 

You  might  recall  encountering  this  peculiar  “logical  inch”  measurement  in  Chapter  11, 
when  we  explored  the  information  available  from  GetDeviceCaps  with  the  LOGPIXELSX 
and  LOGPIXELSY  parameters.  We  quickly  established  that  a  logical  inch  is  different  from  a 
real  inch. 

For  an  EGA,  GetDeviceCaps  reports  that  the  device  has  96  pixels  horizontally  per 
logical  inch  and  72  pixels  vertically  per  logical  inch.  This  means  that  the  raster  fonts  stored 
in  the  COURB.FON,  SSERIFB.FON,  SERIFB.FON,  and  SYMBOLB.FON  files  are  appropriate 
for  display  on  an  EGA.  The  fonts  in  the  Set  # 2  files  are  too  short  for  the  EGA  because  they 
are  based  on  a  lower  vertical  resolution;  the  fonts  in  Set  #4  are  too  wide  because  they  are 
based  on  a  lower  horizontal  resolution. 

Type  Talk  II:  Getting  the  Point 

Type  size  is  expressed  in  units  called  points.  A  point  is  very  close  to  V12  inch,  so  close  that 
it’s  often  defined  as  exactly  V12  inch.  The  point  size  indicates  the  height  of  the  characters. 
For  instance,  when  we  speak  of  12-point  type,  we’re  referring  to  characters  that  are  n/i2  (!40 
inch  high  from  the  top  of  the  ascenders  to  the  bottom  of  the  descenders. 
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In  Windows,  another  convenient  measurement  is  the  “twip”;  this  fabricated  word 
stands  for  “twentieth  of  a  point,”  which  equals  V1440  inch.  Note  that  the  pixels-per-logical- 
inch  measurements  associated  with  each  of  the  five  sets  of  GDI  raster  fonts  are  such  that 
the  size  of  each  pixel  is  an  integral  number  of  twips.  Or  rather,  each  pixel  is  an  integral 
number  of  a  measurement  we  can  call  “logical  twips”: 


Pixels  per  Logical  Inch 

Logical  Twips  per  Pixel 

48 

30 

60 

24 

72 

20 

96 

15 

120 

12 

If  you  run  Microsoft’s  EXEHDR  or  Borland’s  TDUMP  utility  on  the  COURx.FON, 
SSERIFx.FON,  SERIFx.FON,  and  SYMBOLx.FON  font  resource  files,  you’ll  see  in  the  mod¬ 
ule  description  that  the  files  contain  fonts  of  particular  point  sizes.  The  COURx.FON  files 
comprise  10-point,  12-point,  and  15-point  fonts.  The  SSERIFx.FON,  SERIFx.FON,  and  SYM¬ 
BOLx.FON  files  comprise  8-point,  10-point,  12-point,  14-point,  18-point,  and  24-point 
fonts.  The  SMALLx.FON  files  contains  fonts  of  2,  3,  4,  5,  6,  and  7  points. 

But  here’s  the  catch:  These  point  sizes  are  dependent  on  the  resolution  given  by  the 
number  of  pixels  per  logical  inch.  For  instance,  the  24-point  MS  Serif  font  in  the 
SERIFB.FON  file  has  characters  that  are  24  pixels  high.  Only  on  a  display  that  has  72  pixels 
per  vertical  inch  will  the  24  pixels  correspond  to  a  24-point  font.  (Only  raster  fonts  have 
this  problem.  TrueType  fonts  can  be  scaled  to  any  size  you  want  regardless  of  the  resolu¬ 
tion  of  the  video  display.) 

Why  Logical  Inches? 

The  EGA  fonts  are  based  on  a  horizontal  resolution  of  96  pixels  per  inch  and  a  vertical 
resolution  of  72  pixels  per  inch.  The  fact  remains  that  the  EGA  actually  displays  68  pixels 
per  horizontal  inch  and  51  pixels  per  vertical  inch.  The  logical  inch  is  some  40  percent 
larger  than  the  real  inch.  Why  not  simply  base  the  fonts  on  the  real  dimensions  of  the  EGA 
display  and  forget  about  this  logical-inch  business?  There  are  several  reasons. 

On  paper,  8-point  type  with  about  14  characters  per  horizontal  inch  is  perfectly  read¬ 
able.  If  you  were  programming  a  word-processing  or  page-composition  application  for 
Windows,  you  would  want  to  be  able  to  show  legible  8-point  type  on  the  display.  But  if  you 
used  the  actual  dimensions  of  the  video  display,  each  character  would  be  about  6  pixels 
high  and  5  pixels  wide.  Such  characters  would  not  be  legible.  Even  if  the  display  had  suffi¬ 
cient  resolution,  you  might  still  have  problems  reading  actual  8-point  type  on  a  screen. 
When  people  read  print  on  paper,  the  distance  between  the  eyes  and  the  paper  is  gener¬ 
ally  about  a  foot,  but  a  video  display  is  commonly  viewed  from  a  distance  of  2  feet. 
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The  logical  inch  in  effect  provides  a  magnification  of  the  screen,  allowing  the  display 
of  legible  fonts  in  a  size  as  small  as  8-point.  You  can  see  this  magnification  effect  in  Win¬ 
dows  WRITE  when  you  display  the  ruler  at  the  top  of  the  client  area. 

Note  also  that  having  96  pixels  per  logical  inch  horizontally  makes  the  640-pixel¬ 
wide  display  of  the  CGA,  EGA,  and  VGA  equal  to  about  6.5  logical  inches.  This  is  precisely 
the  width  of  text  that  you’ll  print  on  8.5-inch-wide  paper  when  you  use  the  standard 
margins  of  an  inch  on  each  side.  So  the  logical  inch  also  takes  advantage  of  the  width  of  the 
screen  to  allow  text  to  be  displayed  as  large  as  possible. 

This  whole  subject  of  logical  inches  is  relevant  only  for  the  video  display.  For  printers, 
a  logical  inch  is  the  same  as  a  real  inch. 


Type  Talk  III:  Leading  and  Spacing 


When  we  wrote  text  to  the  display  in  Chapter  2,  we  obtained  information  from  GetText- 
Metrics  that  allowed  us  to  space  the  text  properly.  The  six  values  from  the  TEXTMETRIC 
structure  that  describe  the  size  of  a  character  were  shown  in  a  diagram  (Figure  2-3).  Five  of 
those  values  concern  a  character’s  height,  as  shown  in  Figure  14-6. 


tmExternalLeading 
j>-  tmlnternalLeading 


>  tmHeight 


J 
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The  word  leading  (pronounced  “ledding”)  is  derived  from  the  lead  that  typesetters 
insert  between  blocks  of  metal  type  to  add  white  space  between  lines  of  text.  The  tmlnter- 
nalLeading  value  is  the  space  for  diacritics;  tmExternalLeading  “suggests”  an  additional 
space  to  leave  between  lines  of  characters.  Programmers  can  use  or  ignore  the  external 
leading  value. 

When  we  refer  to  a  font  as  being  8-point  or  12-point,  we’re  actually  talking  about  the 
height  of  the  font  less  the  internal  leading.  The  diacritics  on  certain  capital  letters  are  con¬ 
sidered  to  occupy  the  space  that  normally  separates  lines  of  type.  The  tmHeight  value 
refers  to  the  line  spacing. 

Let’s  look  at  some  examples  of  raster  font  heights  and  leading.  I’ll  use  the  EGA  raster 
fonts  for  these  examples  because  the  EGA  very  conveniently  has  72  pixels  per  logical  inch, 
or  1  pixel  per  logical  point. 

In  the  case  of  the  24-point  Times  Roman  font  for  the  EGA,  the  tmHeight  value  is  28 
and  the  tmlnternalLeading  value  is  4.  The  line  spacing  is  28  points.  The  size  of  the  font  is 
28  minus  4,  or  24  points,  as  expected.  We  speak  of  this  as  a  24-point  font  on  a  28-point  line 
spacing,  which  is  often  abbreviated  as  24/28  (pronounced  “twenty-four  on  twenty-eight”). 
The  10-point  MS  Sans  Serif  and  MS  Serif  fonts  designed  for  the  EGA  both  have  a  tmHeight 
value  of  12  and  a  tmlnternalLeadingv  alue  of  2.  The  line  spacing  is  12  points,  or  Vfc  of  a  logi¬ 
cal  inch,  which  is  the  normal  line  spacing  of  a  printer  or  typewriter. 

The  “Logical  Twips”  Mapping  Mode 

When  I  discussed  mapping  modes  in  Chapter  11,  you  might  have  thought  the  MM_TWIPS 
mapping  mode  would  be  used  by  programs  that  make  heavy  use  of  formatted  text.  In  this 
mapping  mode,  logical  units  are  in  terms  of  V20  of  a  point.  However,  you  probably  won’t 
want  to  use  MM_TWIPS  for  the  video  display,  because  the  MM_TWIPS  mapping  mode  is 
based  on  real  inches  rather  than  on  logical  inches.  As  a  result,  your  program  won’t  be  able 
to  display  legible  text  at  normally  readable  font  sizes,  and  it  won’t  be  able  to  equate  the  cor¬ 
rect  point  sizes  (8,  10,  12,  14,  18,  and  24)  of  the  available  raster  fonts  to  their  heights  in 
MM  _TWIPS  units. 

You’ll  be  better  off  if  you  define  your  mapping  mode  based  on  the  logical-pixels-per- 
inch  dimensions  available  from  GetDeviceCaps.  I  call  this  the  “Logical  Twips”  mapping 
mode;  here’s  all  you  need  to  set  it: 

SetMapMode  (hdc,  MM_AN I SOTROP I C )  ; 

SetWindowExt  (hdc,  1440,  1440)  ; 

SetViewportExt  (hdc,  GetDeviceCaps  (hdc,  LOGPIXELSX), 

GetDeviceCaps  (hdc,  LOGPIXELSY) )  ; 

Because  the  pixels-per-logical-inch  values  are  always  divisors  of  1440,  the  scaling  factor  for 
this  mapping  mode  is  an  integer.  With  this  mapping  mode  set,  if  you  want  to  request  a  font 
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with  12-point  line  spacing  (as  we’ll  do  shortly),  you  can  specify  the  height  of  the  font  as  240 
(12  times  20)  logical  units. 

If  you  select  a  font  into  your  device  context  and  call  GetTextMetrics  to  obtain  the 
dimensions  of  the  font,  you  can  calculate  the  type  size  in  points  by  using  the  formula: 

(tm.tmHeight  -  tm.tmlnternalLeading)  /  20 

The  line  spacing  in  points  is  equal  to: 

tm.tmHeight  /  20 

For  some  smaller  fonts  on  low-resolution  devices,  the  size  and  spacing  of  the  type  might 
actually  involve  a  fraction  of  a  point — for  example,  8-point  type  with  8.5-point  line  spac¬ 
ing.  To  round  to  the  nearest  integral  point  size,  you  might  instead  want  to  use  the  formulas: 

(tm.tmHeight  -  tm.tmlnternalLeading  +  10)  /  20 

and: 


(tm.tmHeight  +  10)  /  20 

We’ll  use  the  “Logical  Twips”  mapping  mode  in  the  JUSTIFY  program  toward  the  end  of 
this  chapter. 

Once  again,  remember  that  the  discrepancy  between  logical  inches  and  real  inches 
occurs  only  for  the  display.  If  you  use  the  “Logical  Twips”  mapping  mode  with  a  printer, 
you’ll  simply  duplicate  the  MM_TWIPS  mapping  mode. 


CREATING,  SELECTING, 

AND  DELETING  LOGICAL  FONTS 

Now  that  we’ve  nailed  down  the  concept  of  logical  inches,  it’s  time  to  talk  about  logical 
fonts.  The  logical  font  is  the  final  type  of  GDI  object  I’ll  discuss  in  this  book. 

A  logical  font  is  the  description  of  a  font.  Like  the  logical  pen  and  logical  brush,  it  is  an 
abstract  item  that  becomes  real  only  when  it  is  selected  into  a  device  context.  For  logical 
pens  (for  instance),  you  can  specify  any  color  you  want  for  the  pen,  but  Windows  converts 
that  to  a  pure  color  when  you  select  the  pen  into  the  device  context.  Only  then  does 
Windows  know  about  the  color  capabilities  of  the  device. 

As  I’ll  discuss  shortly,  you  create  a  logical  font  by  first  defining  the  fields  of  a  LOG- 
FONT  structure.  There  are  three  basic  ways  you  can  do  this: 

■  You  can  simply  set  the  fields  of  the  LOGFONT  structure  to  the  charac¬ 
teristics  of  the  font  that  you  want.  In  this  case,  Windows  attempts  to  give 
you  the  font  that  best  matches  these  characteristics. 
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■  You  can  enumerate  all  the  fonts  on  the  device  and  present  the  user  with  a 
choice  using  a  dialog  box.  When  enumerating  raster  fonts,  you  get  one 
LOGFONT  structure  for  each  raster  font  size;  you  can  simply  use  the 
LOGFONT  structure  directly  to  create  the  logical  font.  Because  stroke  and 
TrueType  fonts  are  continuously  scalable,  you  only  get  one  LOGFONT 
structure  for  each  font  name.  In  this  case,  you  need  to  set  a  different  font 
height  in  the  LOGFONT  structure  before  creating  the  logical  font. 

■  You  can  take  the  easy  approach  and  call  the  ChooseFont  function 
included  in  the  Windows  3-1  common  dialog  box  library.  You  get  back  a 
LOGFONT  structure  that  you  can  use  directly  for  creating  the  font. 

These  three  techniques  are  demonstrated  in  this  chapter’s  PICKFONT,  FONTLIST,  and 
JUSTIFY  programs. 

If  you  take  the  first  approach,  the  difference  between  the  logical  font  that  you  request 
and  the  real  font  that  you  get  can  be  considerable.  For  example,  suppose  you  request  a  32- 
point  Zapf  Chancery  font.  Windows  returns  to  your  program  a  handle  to  a  logical  font.  Now 
you  select  that  font  into  a  device  context.  What  happens?  It  depends.  If  the  device  context 
is  a  printer  device  context  for  an  Apple  LaserWriter  Plus,  you  will  indeed  be  able  to  write 
text  to  the  printer  using  a  32-point  Zapf  Chancery  font.  But  if  you  select  this  logical  font  into 
your  screen  device  context,  you’ll  get  something  that  only  approximates  this  font. 

Here  is  the  process  for  creating,  selecting,  and  deleting  logical  fonts: 

1.  Create  a  logical  font  by  calling  CreateFont  or  CreateFontlndirect .  These 
functions  return  a  handle  to  a  font  of  type  HFONT. 

2.  Select  the  logical  font  into  the  device  context  using  SelectObject.  Windows 
chooses  a  real  font  that  most  closely  matches  the  logical  font. 

3.  Determine  the  size  and  the  characteristics  of  the  real  font  with  Get- 
TextMetrics.  (You  can  also  get  the  name  of  the  font  with  GetTextFace .) 

This  information  lets  you  properly  space  the  text  that  you  write  when  this 
font  is  selected  into  the  device  context. 

4.  After  you’ve  finished  using  the  font,  delete  the  logical  font  by  calling 
DeleteObject.  Don’t  delete  the  font  while  it  is  selected  in  a  valid  device 
context,  however,  and  never  delete  stock  fonts. 

Windows  has  two  functions  for  creating  logical  fonts.  The  first  is  almost  never  used: 

hFont  =  CreateFont  (nHeight  .  .  .  1 pszFaceName )  ; 
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The  CreateFont  function  has  more  parameters  than  any  other  Windows  function — 14  of 
them,  in  fact — which  makes  the  function  very  unwieldy. 

Fortunately,  the  CreateFontlndirect  function  uses  a  single  structure  of  type  LOG- 
FONT.  In  most  cases,  using  CreateFontlndirect  and  the  logical  font  structure  is  neater  and 
more  efficient  than  specifying  the  14  parameters  of  CreateFont.  The  LOGFONT  structure 
has  14  fields  that  correspond  directly  to  the  14  parameters  of  CreateFont.  Here’s  the  syntax: 

LOGFONT  logfont  ; 

[other program  lines] 

hFont  =  CreateFontlndi  rect  ( &1  ogf ont )  ; 

After  you  create  a  logical  font,  you  select  it  into  your  device  context  with  SelectObject: 
hFontOld  =  SelectObject  (hdc,  hFont)  ; 

Windows  then  matches  the  logical  font  with  a  real  font.  You  can  determine  the  name  of  the 
typeface  by  using  the  function: 

GetTextFace  (hdc,  sizeof  szFaceName,  szFaceName)  ; 

where  szFaceName  is  a  character  array  to  receive  the  name.  You  can  have  Windows  copy 
the  various  sizes  of  the  font  into  a  structure  of  type  TEXTMETRIC  using  the  familiar: 

GetTextMetrics  (hdc,  &tm)  ; 

The  GetObject  function,  which  you  can  use  to  obtain  information  about  a  logical  pen, 
brush,  or  bitmap,  can  also  be  used  for  logical  fonts: 

GetObject  (hFont,  sizeof  (LOGFONT),  &logfont)  ; 

But  this  function  returns  only  the  information  that  you  put  into  logfont  to  create  the  font 
in  the  first  place. 

You  can  delete  a  logical  font  (but  not  while  it  is  selected  into  a  device  context)  with 
DeleteObject: 

DeleteObject  (hFont)  ; 

It’s  easiest  to  unselect  the  logical  font  from  the  device  context  by  selecting  a  stock  font  into 
the  device  context. 

The  PICKFONT  Program 

With  the  PICKFONT  program,  shown  in  Figure  14-7  beginning  on  the  following  page,  you 
can  define  many  of  the  fields  of  a  LOGFONT  structure.  The  program  creates  a  logical  font 
and  displays  the  characteristics  of  the  real  font  after  the  logical  font  is  selected  into  the 
screen  device  context. 
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PICKFONT.MAK 

#— . 

#  PICKFONT.MAK  make  file 

#  . . 

pickfont.exe  :  pickfont.obj  pickfont.def  pickfont.res 

$ ( WI NLI NK)  pickfont.  pickfont,  NUL,  $(WINLIB),  pickfont 
rc  -t  pickfont.res 

pickfont.obj  :  pickfont. c  pickfont. h 
$ ( W I NCC )  pickfont. c 

pickfont.res  :  pickfont. rc  pickfont. h 
$ ( W I N RC )  pickfont. rc 


PICKFONT.C 

/* . 

PICKFONT.C  --  Font  Picker  Program 

(c)  Charles  Petzold,  1992 
.  . */ 

//include  <windows.h> 

//include  "pickfont. h" 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 
BOOL  FAR  PASCAL  .export  DlgProc  (HWND,  UINT,  UINT,  LONG)  ; 

char  szAppName  []  =  "PickFont"  ; 

DWORD  dwAspectMatch  =  0L  ; 

HWND  hDlg  ; 

LOGFONT  If  ; 

short  nMapMode  =  IDD.TEXT  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 


Figure  14-7.  The  PICKFONT  program. 


(continued) 
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wndcl ass. style  =  CS.HREDRAW  !  CSJ/REDRAW  ; 

wndclass.lpfnWndProc  =  WndProc  ; 

wndclass.cbClsExtra  =  0  ; 

wndclass.cbWndExtra  =  0  ; 

wndclass.hlnstance  =  hlnstance  ; 

wndclass.hlcon  =  Loadlcon  (NULL,  IDI_APPLICATION)  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 

wndclass.lpszMenuName  =  NULL  ; 

wndclass.lpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Font  Picker", 

WS_0V ERLAPPEDWI NDOW  !  WS.CLIPCHILDREN, 
CW_USEDEFAULT,  CW_USEDE FAULT , 

CW.USEDEFAULT,  CW_USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

if  (hDlg  ==  0  ! S  ! IsDi al ogMessage  (hDlg,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

return  msg.wParam  ; 


void  MySetMapMode  (HDC  hdc) 

{ 

if  (nMapMode  ==  IDD.LTWPS) 

{ 

SetMapMode  (hdc.  MM_AN I SOTROPI C )  ; 

SetWindowExt  (hdc.  1440,  1440)  ; 

SetViewportExt  (hdc,  GetDeviceCaps  (hdc,  LOGPIXELSX), 
GetDeviceCaps  (hdc,  LOGPIXELSY) )  ; 

} 

else 

SetMapMode  (hdc,  MM_TEXT  +  nMapMode  -  I DD_TEXT )  ; 

} 

void  ShowMetrics  (HWND  hDlg) 

{ 

static  TEXTMETRIC  tm  ; 
static  struct 


(continued) 
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{ 


short  nDIgID 
int  *pData 
} 

shorts  []  = 

{ 

TM_H EIGHT, 

&tm.tmHeight, 

TM.ASCENT, 

&tm.tmAscent, 

TM_DESCENT, 

&tm.tmDescent, 

TM_I NTLEAD , 

&tm.tmlnternal Leading, 

TM_EXTLEAD, 

&tm.tmExternal Leading, 

TM.AVEWIDTH, 

&tm.tmAveCharWidth, 

TM.MAXWIDTH, 

&tm.tmMaxCharWidth, 

TM_WEIGHT, 

&tm.tmWeight, 

TM_0VER, 

&tm.tmOverhang, 

TM.DIGX, 

&tm. tmDi gi ti zedAspectX , 

TM_DIGY, 

}  ; 

&tm. tmDi gi ti zedAspectY 

static  char  *szFamily  []  =  {  "Don't  Care",  "Roman",  "Swiss", 

"Modern",  "Script",  "Decorative"  }  ; 

BOOL  bTrans  ; 

char  *szCharSet,  szFaceName  [LF_FACESIZE]  ; 

HDC  hdc  ; 

HFONT  hFont  ; 

short  i  ; 

If .lfHeight  =  GetDlgltemlnt  (hDlg,  IDD_HEIGHT,  &bTrans,  TRUE)  ; 

lf.lfWidth  =  GetDlgltemlnt  (hDlg,  IDD_WIDTH,  &bTrans,  FALSE)  ; 

If .lfWeight  =  GetDlgltemlnt  (hDlg,  IDD.WEIGHT,  &bTrans,  FALSE)  ; 

If.lfltalic  =  (BYTE)  (IsDlgButtonChecked  (hDlg,  IDD_ITALIC)  ?  1  :  0) 

If .lfUnderline  =  (BYTE)  (IsDlgButtonChecked  (hDlg,  IDDJJNDER)  ?  1  :  0) 

If .IfStrikeOut  =  (BYTE)  (IsDlgButtonChecked  (hDlg,  IDD.STRIKE)  ?  1  :  0) 

GetDl gltemText  (hDlg,  IDD_FACE,  (char  *)  If .IfFaceName,  LF_FACESIZE)  ; 

dwAspectMatch  =  IsDlgButtonChecked  (hDlg,  IDD.ASPECT)  ?  1L  :  0L  ; 

hdc  =  GetDC  (hDlg)  ; 

MySetMapMode  (hdc)  ; 

SetMapperFlags  (hdc,  dwAspectMatch)  ; 

hFont  =  SelectObject  (hdc,  CreateFontlndi rect  (&lf))  ; 

GetTextMetrics  (hdc,  &tm)  ; 

GetTextFace  (hdc,  sizeof  szFaceName,  szFaceName)  ; 

DeleteObject  (SelectObject  (hdc,  hFont))  ; 

ReleaseDC  (hDlg,  hdc)  ; 
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for  ( 1  =  0  ;  i  <  sizeof  shorts  /  sizeof  shorts  [0]  ;  i++) 

SetDl gltemlnt  (hDlg,  shorts [ i ] .nDl gID,  *shorts[i ] .pData ,  TRUE)  ; 

SetDIgltemText  (hDlg,  TM.PITCH,  tm . tmPi tchAndFami 1 y  &  1  ? 

"VARIABLE" :"FIXEDM)  ; 

SetDIgltemText  (hDlg,  TM_FAMILY,  szFamily  [tm.tmPitchAndFamily  »  4])  ; 
switch  (tm.tmCharSet) 


{ 


case  ANSI.CHARSET  : 

szCharSet  =  "ANSI"  ; 

break 

case  SYMBOL.CHARSET  : 

szCharSet  =  "Symbol"  ; 

break 

case  SHI  FT J I S_CHARSET  : 

szCharSet  =  "Shift"  ; 

break 

case  OEM.CHARSET  : 

szCharSet  =  "OEM"  ; 

break 

default  : 

szCharSet  =  "?????"  ; 

break 

} 

SetDIgltemText  (hDlg,  TM_CHARSET,  szCharSet)  ; 

SetDIgltemText  (hDlg,  TF_NAME,  szFaceName)  ; 

} 

BOOL  FAR  PASCAL  .export  DlgProc  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM_I NITDIALOG  : 

CheckRadioButton  (hDlg,  IDD.TEXT,  IDD.LTWPS,  IDD.TEXT) 

CheckRadioButton  (hDlg,  IDD.ANSI ,  IDD.OEM,  IDD.ANSI) 

CheckRadioButton  (hDlg,  IDD.PDEF,  IDD.PVAR,  IDD.PDEF) 

CheckRadioButton  (hDlg,  IDD.DONT,  IDD.DEC,  IDD.DONT) 

If .IfEscapement  =  0  ; 

If .1  fomentation  =  0  ; 

If.lfQuality  =  DEFAULT.QUALITY  ; 

If .lfOutPrecision  =  OUT_DEFAULT_PRECIS  ; 

If .lfClipPrecision  =  CLI P_DEFAULT_PRECIS  ; 

ShowMetrics  (hDlg)  ; 

//  fall  through 

case  WM.SETFOCUS  : 

SetFocus  (GetDlgltem  (hDlg,  IDD.HEIGHT) )  ; 
return  FALSE  ; 

case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  IDDJTEXT  : 
case  IDD.LOMET  : 
case  IDD.HIMET  : 
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case  IDD_L0ENG  : 
case  IDD.HIENG  : 
case  I DD_TW IPS  : 
case  I DD__LTWPS  : 

CheckRadioButton  (hDlg,  IDD_TEXT,  IDD_LTWPS,  wParam)  ; 
nMapMode  =  wParam  ; 
break  ; 

case  IDD_ASPECT  : 
case  IDD.ITALIC  : 
case  IDDJJNDER  : 
case  IDD_STRIKE  : 

CheckDlgButton  (hDlg,  wParam, 

IsDlgButtonChecked  (hDlg,  wParam)  ?  0  :  1)  ; 
break  ; 

case  IDD_ANSI  : 

lf.lfCharSet  =  ANSI_CHARSET  ; 

CheckRadioButton  (hDlg,  IDD_ANSI.  IDD_0EM,  wParam)  ; 
break  ; 

case  IDD_SYMBOL  : 

lf.lfCharSet  =  SYMBOL.CHARSET  ; 

CheckRadioButton  (hDlg,  IDD_ANSI,  IDD_0EM,  wParam)  ; 
break  ; 

case  I DD_SH I  FT  : 

lf.lfCharSet  =  SHI FTJ IS_CHARSET  ; 

CheckRadioButton  (hDlg,  IDD_ANSI,  IDD_0EM,  wParam)  ; 
break  ; 

case  IDD.OEM  : 

lf.lfCharSet  =  OEM.CHARSET  ; 

CheckRadioButton  (hDlg,  I DD__ANSI ,  IDD_0EM,  wParam)  ; 
break  ; 

case  IDD.PDEF  : 
case  IDD.PFIXED  : 
case  I DD_PVAR  : 

CheckRadioButton  (hDlg,  IDD_PDEF,  IDD.PVAR,  wParam)  ; 

1 f . 1 f Pi tchAndFami ly  &=  0xF0  ; 

If .lfPitchAndFamily  !=  (BYTE)  (wParam  -  IDD_PDEF)  ; 
break  ; 

case  IDD_D0NT  : 
case  IDD.ROMAN  : 
case  IDD_SWISS  : 
case  IDD_MODERN  : 
case  IDD.SCRIPT  : 
case  IDD_DEC  : 
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CheckRadioButton  (hDlg,  IDDJDONT,  IDD_DEC,  wParam)  ; 

If .lfPitchAndFamily  &=  0x0F  ; 

lf.lfPitchAndFamily  !  =  (BYTE)  (wParam  -  IDD_D0NT  «  4)  ; 
break  ; 

case  I DD_0K  : 

ShowMetrics  (hDlg)  ; 

Inval idateRect  (GetParent  (hDlg),  NULL,  TRUE)  ; 
break  ; 

} 

break  ; 

default  : 

return  FALSE  ; 

} 

return  TRUE  ; 

} 


long  FAR  PASCAL  _export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


{ 

static  char 

HANDLE 

HDC 

HFONT 

FARPROC 

PAINTSTRUCT 

RECT 


szText  []  = 

"AaBbCcDdEeFfGgHhli JjKkLlMmNnOoPqQqRrSsTtUuVvWwXxYyZz" 
hlnstance  ; 
hdc  ; 
hFont  ; 
lpfnDlgProc  ; 
ps  ; 
rect  ; 


switch  (message) 

{ 

case  WM_CREATE  : 

hlnstance  =  ((LPCREATESTRUCT)  1 Param)->hlnstance  : 
lpfnDlgProc  =  MakeProcInstance  ((FARPROC)  DlgProc,  hlnstance)  ; 
hDlg  =  CreateDialog  (hlnstance,  szAppName,  hwnd,  lpfnDlgProc)  ; 
return  0  ; 

case  WM_SETFOCUS  : 

SetFocus  (hDlg)  ; 
return  0  ; 

case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

MySetMapMode  (hdc)  ; 

SetMapperFlags  (hdc,  dwAspectMatch)  ; 

GetClientRect  (hDlg,  &rect)  ; 
rect. bottom  +=  1  ; 

DPtoLP  (hdc.  ( LPPOINT)  &rect,  2)  ; 

hFont  =  SelectObject  (hdc,  CreateFontlndi rect  (&lf))  ; 
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TextOut  (hdc,  rect.left,  rect. bottom,  szText,  52)  ; 

DeleteObject  (SelectObject  (hdc,  hFont ) )  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM.DESTROY  : 

PostQuitMessage  (0)  : 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


PICKFONT.RC 

/*--- . 

PICKFONT.RC  resource  script 

. - . */ 

♦include  <windows.h> 

#1 ncl ude  "pickfont.h" 

♦define  GT  (WS.GROUP  !  WS.TABSTOP) 

♦define  GR  (WS.GROUP) 

♦define  TA  (WS.TABSTOP) 

♦define  AS  (ES_AUT0HSCR0LL) 

PickFont  DIALOG  0,  0,  320,  170 

STYLE  W S_C H I L D  !  WS.BORDER  !  INVISIBLE  !  DS_ABSALIGN 


{ 


LTEXT 

"Weight" 

-1, 

6, 

8, 

30. 

8 

EDITTEXT 

I DD_HE I GHT , 

36, 

6, 

30, 

12 

LTEXT 

"Width" 

■1. 

6, 

24, 

30, 

8 

EDITTEXT 

I DD_W I DTH , 

36, 

22, 

30, 

12 

LTEXT 

"Weigh&t" 

-1. 

6, 

40, 

30, 

8 

EDITTEXT 

I DD_WEI GHT , 

36, 

38, 

30, 

12 

GROUPBOX 

"&Mapping  Mode" 

-1, 

70, 

2, 

116, 

60 

RADIOBUTTON 

"Text" 

IDDJTEXT, 

74, 

12, 

50, 

12, 

GT 

RADIOBUTTON 

"Lo  Metric" 

IDD.LOMET, 

74, 

24, 

50. 

12 

RADIOBUTTON 

"Hi  Metric" 

IDD_HIMET, 

74, 

36, 

50, 

12 

RADIOBUTTON 

"Lo  English" 

IDD_L0ENG, 

130, 

12, 

54, 

12 

RADIOBUTTON 

"Hi  English" 

IDD_HIENG, 

130, 

24, 

52, 

12 

RADIOBUTTON 

"Twips" 

IDD.TWIPS, 

130, 

36, 

52, 

12 

RADIOBUTTON 

"'Logical  Twips'", 

IDD_LTWPS, 

74, 

48, 

80. 

12 

CHECKBOX 

"Match  &Aspect" 

IDD_ASPECT, 

6. 

52, 

60, 

12, 

GT 

CHECKBOX 

"Altai  1c" 

IDD_ITALIC, 

6, 

64, 

60, 

12, 

GT 

CHECKBOX 

"&Underline" 

IDDJJNDER, 

6, 

76, 

60, 

12, 

GT 

CHECKBOX 

"&Strike-Out" 

IDD_STRIKE, 

6, 

88. 

60, 

12, 

GT 
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GROUPBOX 

"&Pitch" 

-1, 

4, 

102, 

58. 

48, 

GR 

RADIOBUTTON 

"Default” 

IDD_PDEF, 

8, 

112. 

50, 

12. 

GT 

RADIOBUTTON 

"Fixed" 

IDD_PFIXED, 

8, 

124, 

50. 

12 

RADIOBUTTON 

"Variable" 

IDD_PVAR, 

8, 

136, 

50, 

12 

GROUPBOX 

"&Char  Set" 

-1, 

66, 

90, 

58. 

60, 

GR 

RADIOBUTTON 

"ANSI" 

IDD__ANSI , 

70, 

100, 

50, 

12, 

GT 

RADIOBUTTON 

"Symbol" 

IDD_SYMBOL, 

70, 

112, 

50, 

12 

RADIOBUTTON 

"Shift  JIS" 

IDD_SHIFT, 

70, 

124. 

50. 

12 

RADIOBUTTON 

"OEM" 

IDD_0EM, 

70, 

136, 

50, 

12 

GROUPBOX 

"&Family" 

-1. 

128, 

66, 

58. 

84, 

GR 

RADIOBUTTON 

"Don't  Care" 

IDD_DONT, 

132, 

76, 

50, 

12, 

GT 

RADIOBUTTON 

"Roman" 

IDD.ROMAN, 

132, 

88. 

50, 

12 

RADIOBUTTON 

"Swiss" 

IDD.SWISS, 

132, 

100, 

50, 

12 

RADIOBUTTON 

"Modern" 

IDD_MODERN, 

132, 

112, 

50, 

12 

RADIOBUTTON 

"Script" 

IDD_SCRIPT, 

132, 

124, 

50, 

12 

RADIOBUTTON 

"Decorative" 

IDD_DEC, 

132, 

136, 

50, 

12 

LTEXT 

"Face  &Name" 

-1. 

4, 

154, 

42, 

8 

EDITTEXT 

IDD.FACE, 

48. 

152, 

74, 

14. 

AS 

DEFPUSHBUTTON 

"&0k" 

IDD_0K, 

126, 

152, 

60, 

14, 

GT 

GROUPBOX 

"Text  Metrics" 

-1, 

192, 

2, 

110, 

164, 

GR 

LTEXT 

"Height:" 

-1, 

200, 

14, 

44, 

8 

LTEXT 

"Ascent:" 

-1, 

200, 

24, 

44, 

8 

LTEXT 

"Descent:" 

-1, 

200, 

34, 

46, 

8 

LTEXT 

"Int  Lead:" 

-1. 

200, 

44, 

44, 

8 

LTEXT 

"Ext  Lead:" 

'1. 

200, 

54, 

44, 

8 

LTEXT 

"Ave  Width:" 

-1, 

200, 

64, 

44, 

8 

LTEXT 

"Max  Width:" 

-1, 

200, 

74, 

44, 

8 

LTEXT 

"Weight:" 

-1. 

200, 

84, 

44, 

8 

LTEXT 

"Pitch:" 

-1, 

200, 

94, 

44, 

8 

LTEXT 

"Family:" 

-1, 

200, 

104, 

42, 

8 

LTEXT 

"Char  Set:" 

-1. 

200, 

114, 

44, 

8 

LTEXT 

"Overhang:" 

-1, 

200, 

124, 

44, 

8 

LTEXT 

"X  Aspect:" 

-1, 

200, 

134, 

44, 

8 

LTEXT 

"Y  Aspect:" 

-1, 

200, 

144, 

44, 

8 

LTEXT 

"Face  Name:" 

-1. 

200, 

154, 

44, 

8 

RTEXT 

••0” 

TM_H EIGHT, 

250, 

14, 

44, 

8 

RTEXT 

"0" 

TM_ASCENT, 

250, 

24, 

44, 

8 

RTEXT 

"0” 

TM_DESCENT, 

250, 

34, 

44, 

8 

RTEXT 

H0M 

TM_EXTLEAD, 

250, 

54, 

44, 

8 

RTEXT 

”0" 

TM_INTLEAD, 

250, 

44, 

44, 

8 

RTEXT 

"0” 

TM_AVEWIDTH, 

250, 

64, 

44, 

8 

RTEXT 

,,0" 

TM.MAXWIDTH, 

250, 

74, 

44, 

8 

RTEXT 

”0" 

TM_W EIGHT, 

250, 

84, 

44. 

8 

RTEXT 

II  II 

TM_PITCH, 

250, 

94, 

44, 

8 

RTEXT 

II  II 

TM_FAMILY, 

250, 

104, 

44, 

8 

RTEXT 

II  II 

TM.CHARSET, 

250, 

114, 

44, 

8 

RTEXT 

"  0  " 

TM_0VER, 

250, 

124. 

44, 

8 

RTEXT 

"0" 

TM_DIGX, 

250, 

134, 

44, 

8 

RTEXT 

”0” 

TM_DIGY, 

250, 

144, 

44, 

8 

RTEXT 

ii  ii 

TF_NAME, 

250, 

154, 

44, 

8 

> 
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PICKFONT.H 

/* . 

PICKFONT.H  header  file 


//define  IDD_0K  1 
#define  IDD_HEIGHT  10 
//define  IDD_WIDTH  11 
//define  I DD_WEI GHT  12 
//define  IDO_ITALIC  13 
//define  IDDJJNDER  14 
//define  IDD_STRIKE  15 
//define  IDD_ASPECT  16 
//define  IDD_TEXT  17 
//define  IDDJ.0MET  18 
//define  ID0_HIMET  19 
//define  IDD_L0ENG  20 
//define  I  DD_H  I  ENG  21 
//define  IDD_TWIPS  22 
//define  IDD_LTWPS  23 
//define  IDD_ANSI  24 
//define  IDD_SYMBOL  25 
//define  I DD_SHI FT  26 
//define  I DD_0EM  27 
//define  IDD_PDEF  28 
//define  IDD_PFIXED  29 
//define  IDD.PVAR  30 
//define  I DD_D0NT  31 
//define  IDD_R0MAN  32 
//define  IDD_SWISS  33 
//define  IDD_MODERN  34 
//define  IDD_SCRIPT  35 
//define  IDD_DEC  36 
//define  IDD_FACE  37 
//define  TM_HEIGHT  38 
//define  TM_ASCENT  39 
//define  TM_DESCENT  40 
//define  TM_INTLEAD  41 
//define  TM_EXTLEAD  42 
//define  TM_AVEWIDTH  43 
//define  TM_MAXWIDTH  44 
//define  TM_WE  I  GHT  45 
//define  TM_PITCH  46 
//define  TM_FAMILY  47 
//define  TM_CHARSET  48 
//define  TM_0VER  49 
//define  TM_DIGX  50 
//define  TM_DIGY  51 
//define  TF.NAME  52 
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PICKFONT.DEF 


PICKFONT.DEF  module  definition  file 


NAME 


PICKFONT 


DESCRIPTION  'Font  Picker  Program  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


Figure  14-8  shows  a  typical  PICKFONT  screen.  The  left  side  of  the  PICKFONT  display 
is  a  modeless  dialog  box  that  allows  you  to  select  most  of  the  fields  of  the  logical  font  struc¬ 
ture.  The  right  side  shows  the  results  of  GetTextMetrics  after  the  font  is  selected  into  the 
device  context.  A  sample  line  of  text  using  this  font  appears  at  the  bottom  of  the  screen. 

The  modeless  dialog  box  also  contains  some  options  that  are  not  part  of  the  logical 
font  structure.  These  are  the  mapping  mode  (including  my  “Logical  Twips”  mapping 
mode)  and  the  Match  Aspect  option,  which  changes  the  way  Windows  matches  a  logical 
font  to  a  real  font. 


Height 
Width  [ 
Weight  | 

D  Match  Aspect 
Italic 

□  Underline 


Mapping  Mode 

®Text  O  Lo  English 

O  Lo  Metric  O  Hi  English 

O  Hi  Metric  O  Twips 

O  'Logical  Twips* 


□  Strike-Out 

Char  Set 

Pitch 

®  ANSI 

<§>  Default 

O  Symbol 

O  Fixed 

O  Shift  JIS 

O  Variable 

O  OEM 

Family 
®  Don't  Care 
O  Roman 
O  Swiss 
O  Modern 
O  Script 
O  Decorative 


Face  Name  Arial 


Ok 


“Text  Metrics 

Height: 

23 

Ascent: 

18 

Descent: 

5 

Int  Lead: 

4 

Ext  Lead: 

1 

Ave  Width: 

8 

Max  Width: 

22 

Weight: 

400 

Pitch: 

VARIABLE 

Family: 

Swiss 

Char  Set: 

ANSI 

Overhang: 

0 

X  Aspect: 

96 

Y  Aspect: 

96 

i 

Face  Name: 

Arial 

\\AaBbCcDdEeFfGgHhfiJjKkLIMmNnOoPqQqRrSs  TtUu  VvWwXxYyZz 


Program  File  Manager 
Manager 


Figure  14-8.  A  typical  PICKFONT  display. 
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Much  of  the  PICKFONT  program  contains  the  logic  necessary  to  maintain  the  dialog 
box,  so  I  won’t  go  into  detail  on  the  workings  of  the  program.  Instead,  I’ll  explain  what 
you’re  doing  when  you  create  and  select  a  logical  font. 

The  Logical  Font  Structure 

As  I  mentioned,  the  best  way  to  create  a  logical  font  is  to  first  define  a  structure  of  type 
LOGFONT: 

LOGFONT  1  ogfont  ; 

When  you  call  CreateFontlndirect ,  you  give  Windows  a  pointer  to  this  structure: 

hFont  =  CreateFontlndi rect  ( &1  ogfont )  ; 

You  don’t  need  to  set  each  and  every  field  of  the  LOGFONT  structure.  If  your  logical 
font  structure  is  defined  as  a  static  variable,  all  the  fields  will  be  initialized  to  0.  The  0  values 
are  defaults.  You  can  use  that  structure  directly  without  any  changes,  and  CreateFont¬ 
lndirect  will  return  a  handle  to  a  font.  When  you  select  that  font  into  the  device  context, 
you’ll  get  a  reasonable  default  font.  You  can  be  as  specific  or  as  vague  as  you  want  in  the 
LOGFONT  structure,  and  Windows  will  attempt  to  match  your  requests  with  a  real  font. 

The  first  two  fields  of  the  LOGFONT  structure  are  in  logical  units,  so  they  depend  on 
the  current  setting  of  the  mapping  mode: 

■  If  Height  (short  integer) — This  is  the  desired  height  of  the  characters 
(including  internal  leading  but  not  external  leading)  in  logical  units. 

Because  the  point  size  of  the  font  itself  is  the  height  of  the  font  less 
internal  leading,  you’re  really  specifying  line  spacing  here.  You  can  set 
If  Height  to  0  for  a  default  size.  If  you  set  If  Height  to  a  negative  number, 
Windows  treats  the  absolute  value  of  that  number  as  a  desired  font  height 
size  rather  than  a  line  spacing.  If  you  want  a  font  of  a  particular  point  size, 
convert  that  point  size  to  logical  units,  and  set  the  If  Height  field  to  the 
negative  of  that  value. 

■  IfWidth  (short  integer) — This  is  the  desired  width  of  the  characters  in 
logical  units.  In  most  cases,  you’ll  want  to  set  this  to  0  and  let  Windows 
choose  a  font  based  solely  on  the  height.  If  you  use  a  nonzero  value, 
Windows  might  be  forced  to  use  a  raster  font  designed  for  a  different 
aspect  ratio  than  that  of  the  device  context  into  which  you  later  select 
the  font.  However,  you  can  use  this  field  with  TrueType  fonts  without 
problems. 

The  next  two  fields  specify  the  “escapement”  and  “orientation”  of  the  text.  In  theory, 
If. 'Escapement  allows  character  strings  to  be  written  at  an  angle,  and  IfOrientation  allows 
characters  to  be  tilted.  These  two  fields  are  not  included  in  the  PICKFONT  program, 
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however.  Before  you  try  to  use  these  fields  on  a  device,  you  should  use  the  TEXTCAPS 
index  to  GetDeviceCaps  to  check  the  device’s  character-rotation  capability. 

■  IfEscapement  (short  integer) — This  is  an  angle  in  tenths  of  a  degree, 
measured  from  the  horizontal  in  a  counterclockwise  direction.  It  spe¬ 
cifies  the  placement  of  the  string  when  you  write  text  with  TextOut.  Here 
are  some  examples: 


Value 

Placement  of  Characters 

0 

Run  from  left  to  right  (default) 

900 

Go  up 

1800 

Run  from  right  to  left 

2700 

Go  down 

■  If  Orientation  (short  integer) — This  is  an  angle  in  tenths  of  a  degree, 
measured  from  the  horizontal  in  a  counterclockwise  direction.  It 
specifies  the  appearance  of  each  character.  Here  are  some  examples: 


Value 

Character  Appearance 

0 

Normal  (default) 

900 

Tipped  90  degrees  tp  the  left 

1800 

Upside  down 

2700 

Tipped  90  degrees  to  the  right 

The  remaining  10  fields  follow: 

■  IfWeight  (short  integer) — This  field  allows  you  to  specify  boldface. 
Currently,  there  are  only  two  recommended  values: 


Value 

Result 

400 

Normal 

700 

Boldface 

In  actuality,  any  value  from  0  to  550  is  normal,  and  any  value  greater 
than  550  is  boldface.  If  you  like  to  plan  for  the  future,  WINDOWS.H  has  a 
collection  of  font  weight  identifiers: 
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Value 

Identifier 

0 

FW-DONTCARE 

100 

FW-THIN 

200 

FW-EXTR ALIGHT  or  FW-ULTR ALIGHT 

300 

FW-LIGHT 

400 

FW.NORMAL  or  FW-REGULAR 

500 

FW-MEDIUM 

600 

FW-SEMIBOLD  or  FW-DEMIBOLD 

700 

FW.BOLD 

800 

FW-EXTRABOLD  or  FW-ULTR ABOLD 

900 

FW_  HEAVY  or  FW-BLACK 

■  Ifltalic  (BYTE) — When  nonzero,  this  specifies  italics.  Windows  can 
synthesize  italics  on  GDI  raster  and  stroke  fonts  and  can  use  italic  or 
oblique  TrueType  fonts.  To  determine  what  a  particular  device  can  do 
with  a  device  font,  check  the  TC_IA_ABLE  bit  of  the  TEXTCAPS  value 
returned  from  GetDeviceCaps. 

■  IfUnderline  (BYTE) — When  nonzero,  this  specifies  underlining,  which 
is  synthesized  on  GDI  fonts.  For  device  fonts,  check  the  TC_UA_ABLE  bit 
returned  from  GetDeviceCaps. 

■  If StrikeOut  (BYTE) — When  nonzero,  this  specifies  that  the  font  should 
have  a  line  drawn  through  the  characters.  This  also  is  synthesized  on  GDI 
fonts.  For  device  fonts,  check  the  TC_SO_ABLE  bit. 

■  IfCharSet  (BYTE)— This  is  the  character  set  of  the  font.  WINDOWS.H 
currently  defines  four  identifiers  for  the  character  set: 


Value 

Identifier 

0 

ANSI_CHARSET 

2 

SYMBOL-CHARSET 

128 

SHIFTJIS-CHARSET  (Japanese  Kanji) 

255 

OEM-CHARSET 

Note:  The  Kanji  character  sets  are  not  included  with  American  or  Euro¬ 
pean  releases  of  Windows. 
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■  If  OutPrecision  (BYTE) — This  specifies  how  Windows  should  attempt  to 
match  the  desired  font  sizes  and  characteristics  with  actual  fonts.  This 
field  is  not  implemented  in  the  PICKFONT  program.  WINDOWS.H 
contains  eight  identifiers  for  the  field: 


Value 

Identifier 

0 

OUT_DEFAULT_PRECIS 

1 

OUT_STRING_PRECIS 

2 

OUT_CHARACTER_PRECIS 

3 

OUT_STROKE_PRECIS 

4 

OUT_TT_PRECIS 

5 

OUT_DEVICE_PRECIS 

6 

OUT_RASTER_PRECIS 

7 

OUT_TT_ONLY_PRECIS 

■  IfClipPrecision  (BYTE) — This  specifies  how  to  clip  characters  that  are 
partly  outside  the  clipping  region.  The  field  is  not  implemented  in  the 
PICKFONT  program.  WINDOWS.H  contains  seven  identifiers: 


Value 

Identifier 

0 

CLIP-DEFAULT-PRECIS 

1 

CLIP-CHARACTER-PRECIS 

2 

CLIP_STROKE_PRECIS 

OxOF 

CLIP-MASK 

0x10 

CLIP-LH -ANGLES 

0x20 

CLIP_TT_ALWAYS 

0x80 

CLIP-EMBEDDED 

■  If  Quality  (BYTE) — This  is  actually  an  instruction  to  Windows  regarding 
the  matching  of  a  desired  font  with  a  real  font.  This  option  is  not  included 
in  the  PICKFONT  program.  There  are  three  identifiers  you  can  use: 


Value 

Identifier 

0 

DEFAULT-QUALITY 

1 

DRAFT-QUALITY 

2 

PROOF-QUALITY 
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If  you  specify  PROOF- QUALITY,  you’re  telling  Windows  that  you  don’t 
want  a  raster  font  to  be  increased  to  a  larger  size  to  match  the  character 
height  or  width  that  you  request.  The  PROOF-QUALITY  fonts  are  the 
most  attractive,  but  they  may  be  smaller  than  what  you  request. 

■  IfPitchAndFamily  (BYTE) — This  byte  is  composed  of  two  parts.  You  can 
use  the  C  OR  operator  to  combine  two  identifiers  for  this  field.  The  lowest 
two  bits  specify  the  pitch  of  the  font: 


Value 

Identifier 

0 

DEFAULT-PITCH 

1 

FIXED-PITCH 

2 

VARIABLE-PITCH 

If  you  specify  FIXED-PITCH,  Windows  will  pick  a  font  that  has  a  fixed 
pitch,  because  you’re  essentially  telling  Windows  that  your  program  can’t 
deal  with  variable-pitch  fonts. 

The  upper  half  of  this  byte  specifies  the  font  family: 


Value 

Identifier 

0x00 

FF-DONTCARE 

0x10 

FF-ROMAN 

0x20 

FF.SWISS 

0x30 

FF-MODERN 

0x40 

FF-SCRIPT 

0x50 

FF-DECORATIVE 

■  IfFaceName  (BYTE  array) — This  is  the  name  of  a  typeface  (such  as 
Courier,  Arial,  or  Times  New  Roman).  WINDOWS.H  includes  an  LF- 
-FACESIZE  identifier  that  equals  32,  which  is  the  maximum  number  of 
characters  allowed  for  the  typeface  name. 

If  you  want  a  TrueType  italic  or  boldface  font,  you  can  get  it  in  one  of 
two  ways.  You  can  use  the  complete  typeface  name  (such  as  Times  New 
Roman  Italic)  in  the  IfFaceName  field,  or  you  can  use  the  base  name 
(Times  New  Roman)  and  set  the  If  Italic  flag. 

The  Font-Mapping  Algorithm 

After  you  set  up  the  logical  font  structure,  you  call  CreateFontlndirectl o  get  a  handle  to  the 
logical  font.  When  you  use  SelectObject  to  select  that  logical  font  into  a  device  context, 
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Windows  finds  the  real  font  that  most  closely  matches  the  request.  In  doing  so,  it  uses  a 
“font-mapping  algorithm.”  Certain  fields  of  the  structure  are  more  important  than  other 
fields. 

The  best  way  to  get  a  feel  for  font  mapping  is  to  spend  an  hour  or  so  experimenting 
with  PICKFONT.  Here  are  some  general  guidelines: 

■  The  If CharSet  (character  set)  field  is  very  important.  For  the  display,  if  you 
specify  OEM_CHARSET,  you’ll  get  either  one  of  the  stroke  fonts  or  the 
terminal  font,  because  these  are  the  only  fonts  that  use  the  OEM  character 
set.  You  must  specify  OEM -CHARSET  if  you  want  to  use  a  GDI  stroke 
font.  A  value  of  ANSI -CHARSET  always  gives  you  a  raster  font  or  a  True¬ 
Type  font.  You’ll  need  to  use  SYMBOL-CHARSET  to  get  the  Symbol  font 
or  the  Wingdings  font. 

■  A  pitch  value  of  FIXED-PITCH  in  the  If  Pitch AndFamily  field  is  im¬ 

portant,  because  you  are  in  effect  telling  Windows  that  you  don’t  want  to 
deal  with  a  variable-pitch  font.  i 

■  The  IfFaceName  field  is  important,  because  you’re  being  specific  about 
the  typeface  of  the  font  that  you  want.  If  you  leave  IfFaceName  set  to 
NULL  and  set  the  If  Family  field  to  a  value  other  than  FF-DONTCARE,  the 
latter  field  becomes  important,  because  you’re  being  specific  about  the 
font  family. 

■  For  raster  fonts,  Windows  will  attempt  to  match  the  IfHeight  value  even  if 
it  needs  to  increase  the  size  of  a  smaller  font.  The  height  of  the  actual  font 
will  always  be  less  than  or  equal  to  that  of  the  requested  font  unless  there 
is  no  font  small  enough  to  satisfy  your  request.  For  stroke  or  TrueType 
fonts,  Windows  will  simply  scale  the  font  to  the  desired  height. 

■  You  can  prevent  Windows  from  scaling  a  raster  font  by  setting  If  Quality 
to  PROOF-QUALITY.  By  doing  so,  you’re  telling  Windows  that  the 
requested  height  of  the  font  is  less  important  than  the  appearance  of 
the  font. 

■  If  you  specify  IfHeight  and  IfWidth  values  that  are  out  of  line  for  the 
particular  aspect  ratio  of  the  display,  Windows  can  map  to  a  raster  font 
that  is  designed  for  a  display  or  other  device  of  a  different  aspect  ratio. 

You  can  use  this  trick  to  get  a  particularly  thin  or  fat  font.  In  general, 
however,  you’ll  probably  want  to  avoid  this  situation,  which  you  do  in 
PICKFONT  by  clicking  the  check  box  marked  Match  Aspect.  If  this  box  is 
checked,  PICKFONT  makes  a  call  to  SetMapperFlags  with  a  flag  set  to  1: 

SetMapperFlags  (hdc,  1L)  ; 
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This  specifies  that  Windows  should  only  match  raster  fonts  that  have  the 
same  aspect  ratio  as  the  device.  You  can  get  fonts  of  other  aspect  ratios  by 
setting  the  mapper  flag  back  to  the  default  value: 

SetMapperFl ags  (hdc,  0L)  ; 

This  doesn’t  affect  TrueType  fonts.  For  TrueType  fonts,  you  can  use  the 
If  Width  font  to  get  a  wider  or  narrower  font  than  normal.  The  approach 
you’ll  want  to  take  is  this:  First,  use  an  If  Width  field  of  0  to  get  a  font  with  a 
normal  width.  You  can  get  the  average  character  width  from  the  tmWidth 
field  of  the  TEXTMETRIC  structure.  At  that  point,  scale  the  value  up  or 
down.  Now  set  the  IfWidth  field  to  the  scaled  value  to  create  another  font. 

Delete  the  first  font. 

If  you  don’t  like  the  way  that  Windows  weights  the  various  characteristics  of  the  logi¬ 
cal  font  to  match  a  real  font,  you  can  change  the  weighting  using  the  SetFontMapperFlags 
function. 

Finding  Out  About  the  Font 

At  the  right  side  of  its  client  area,  PICKFONT  shows  you  the  type  of  information  you  can 
obtain  after  you  select  the  logical  font  into  the  device  context.  GetText Metrics  tells  you  the 
real  characteristics  of  the  font,  and  GetTextFace  tells  you  the  typeface  name. 

To  obtain  the  typeface  name,  you  first  define  a  character  array  to  receive  the  name: 

char  szFaceName  [LF_FACESIZE]  ; 

The  LF_FACESIZE  identifier  is  the  maximum  number  of  characters  in  the  typeface  name. 
You  then  tell  Windows  to  copy  the  typeface  name  into  this  array: 

GetTextFace  (hdc,  sizeof  szFaceName,  szFaceName)  ; 

The  GetTextMetrics  function  retrieves  information  about  the  size  and  other  characteristics 
of  the  font  currently  selected  in  the  device  context: 

TEXTMETRIC  tm  ; 

[other program  lines] 

GetTextMetrics  (hdc,  &tm)  ; 

All  the  size  values  that  Windows  copies  into  the  TEXTMETRIC  structure  are  in  logical 
units  except  for  the  digitized  aspect  ratios.  The  fields  of  the  TEXTMETRIC  structure  are 
as  follows: 

■  tmHeight  (short  integer) — The  height  of  the  character  in  logical  units. 

This  is  the  value  that  should  approximate  the  If  Height  field  specified  in 
the  LOGFONT  structure.  It  is  the  sum  of  the  tmAscent  and  tmDescent 
fields.  Like  the  IfHeight  field  in  the  LOGFONT  structure,  it  actually 
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represents  the  line  spacing  of  the  font  rather  than  the  size,  because  it 
includes  internal  leading.  If  the  If  Height  field  passed  to  the  LOGFONT 
structure  was  negative,  the  tmHeight  field  minus  the  tmlnternalLeading 
field  should  approximate  the  absolute  value  of  the  If  Height  field. 

■  tmAscent  (short  integer) — The  height  of  the  character  above  the  base¬ 
line  in  logical  units. 

■  tmDescent  (short  integer) — The  height  of  the  character  below  the  base¬ 
line  in  logical  units. 

■  tmlnternalLeading  (short  integer) — The  area  used  for  diacritics  on  some 
capital  letters.  As  noted  above,  the  internal  leading  is  included  in  the 
tmHeight  value.  You  can  calculate  the  point  size  of  the  font  by  subtracting 
the  tmlnternalLeading  value  from  the  tmHeight  value. 

■  tmExternalLeading  (short  integer) — An  additional  amount  of  line 
spacing  (beyond  tmHeight)  recommended  by  the  designer  of  the  font. 

■  tmAveCharWidth  (short  integer) — The  average  width  of  the  characters 
in  logical  units. 

■  tmMaxCharWidth  (short  integer) — The  width  of  the  widest  character  in 
logical  units.  This  value  is  the  same  as  tmAveCharWidth  for  a  fixed-pitch 
font. 

■  tmWeight  (short  integer) — The  weight  of  the  font,  ranging  from  0  to  999. 
Currently,  it  will  be  set  to  either  400  (normal)  or  700  (boldface). 

■  tmltalic  (BYTE) — Nonzero  for  an  italic  font. 

■  tmUnderlined  (BYTE) — Nonzero  for  an  underlined  font. 

■  tmStruckOut  (BYTE) — Nonzero  for  a  strikethrough  font. 

■  tmPitchAndFamily  (BYTE) — A  value  comprising  the  pitch  in  the  lower 
two  bits  and  the  family  in  the  higher  four  bits.  This  field  is  coded  the  same 
way  as  the  IfPitchAndFamily  field  in  the  LOGFONT  structure,  and  you 
can  use  the  same  identifiers  to  extract  the  information. 

■  tmCharSet  (BYTE) — The  character  set.  For  programs  running  under 
an  American  or  a  European  version  of  Windows,  it  will  be  either  0 
(ANSI -CHARSET),  2  (SYMBOL-CHARSET)  or  255  (OEM -CHARSET). 

■  tmOverhang  (short  integer) — The  amount  of  extra  width  (in  logical 
units)  that  Windows  adds  to  a  character  when  synthesizing  italic  or 
boldface.  When  a  font  is  italicized,  the  tmAveCharWidth  value  remains 
unchanged,  because  a  string  of  italicized  characters  has  the  same  overall 
width  as  the  same  string  of  normal  characters.  For  boldfacing,  Windows 
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must  slightly  expand  the  width  of  each  character.  For  a  boldface  font,  the 
tmAveCharWidth  value  less  the  tmOverhang  value  equals  the  tmAve- 
CharWidth  value  for  the  same  font  without  boldfacing. 

■  tmDigitizedAspectX  and  tmDigitizedAspectY  (short  integers) — The  as¬ 
pect  ratio  for  which  the  font  is  appropriate.  If  you  specify  Proof  (under 
Quality)  and  check  Match  Aspect  in  PICKFONT,  then  for  most  devices 
these  values  will  be  equivalent  to  the  pixels-per-logical-inch  values 
returned  from  GetDeviceCaps.  Note,  however,  that  these  two  TEXT- 
METRIC  fields  are  switched  around  in  relation  to  the  corresponding 
GetDeviceCaps  parameters:  tmDigitizedAspectX  is  equivalent  to  the  Get¬ 
DeviceCaps  value  for  the  LOGPIXELSY  parameter,  and  tmDigitized¬ 
AspectY  is  equivalent  to  the  value  for  LOGPIXELSX.  If  a  raster  font  is 
scaled  to  a  larger  size,  the  tmDigitizedAspectX  and  tmDigitizedAspectY 
values  increase  accordingly. 

Because  of  space  restrictions,  the  following  four  fields  were  not  included  on  the 
display  screen  of  the  PICKFONTS  program: 

■  tmFirstChar  (BYTE) — The  character  code  of  the  first  character  in  the 
font.  For  ANSI -CHARSET  fonts,  this  is  normally  32,  the  space  character. 

■  tmLastChar  (BYTE) — The  character  code  of  the  last  character  in  the 
font.  For  ANSI -CHARSET  fonts,  this  is  normally  253. 

■  tmDefaultChar  (BYTE) — The  character  that  Windows  uses  to  display 
characters  that  are  not  in  the  font.  For  ANSI -CHARSET  fonts,  this  is 
normally  128. 

■  tmBreakChar  (BYTE) — The  character  that  Windows  (and  your  pro¬ 
grams)  should  use  to  determine  word  breaks  when  justifying  text.  For 
ANSI_CHARSET  fonts,  this  is  normally  32,  the  space  character. 

ENUMERATING  THE  FONTS 

Earlier  in  the  chapter,  I  covered  the  particular  typefaces  and  sizes  that  are  available  when 
you’re  writing  a  program  to  display  text  on  the  screen.  However,  the  user  may  have  in¬ 
stalled  additional  screen  fonts.  But  if  you  want  to  send  text  to  a  printer,  how  do  you  know 
what  fonts  the  printer  has?  The  function  that  lets  you  know  about  all  the  fonts  available  on 
a  device  is  EnumFonts.  EnumFonts  uses  a  call-back  function  that  Windows  calls  once 
for  each  typeface  or  font. 

You  use  EnumFonts  in  one  of  two  ways.  The  first  requires  that  the  second  parameter 
be  NULL: 

EnumFonts  (hdc,  NULL,  1 pfnEnumFuncti on ,  lpData)  ; 
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The  IpfnEnumFunction  parameter  is  a  pointer  to  the  call-back  function.  EnumFonts  calls 
this  call-back  function  once  for  each  typeface  name  available  on  the  device  indicated  by 
the  hdc  parameter.  Normally,  you  use  EnumFonts  this  way  first  to  get  a  list  of  all  typefaces 
supported  by  the  device. 

After  you  have  the  list  of  typeface  names,  you  can  call  EnumFonts  once  for  each 
typeface: 

EnumFonts  (hdc,  szTypeFace,  IpfnEnumFunction,  lpData)  ; 

For  each  call  you  make  to  EnumFonts  in  this  format,  Windows  calls  EnumFunction  once 
for  each  available  size  of  the  particular  typeface. 

The  call-back  function  has  the  format: 

short  FAR  PASCAL  .export  EnumFunction  ( LPLOGFONT  lplf, 

LPTEXTMETRIC  lptm,  short  nFontType,  LPSTR  lpData) 

{ 

[program  lines] 
return  1  ; 

} 

You  must  obtain  a  pointer  to  the  function  with  MakeProcInstance : 

FARPROC  IpfnEnumFunction  ; 

[other program  lines] 

IpfnEnumFunction  =  MakeProcInstance  (EnumFunction,  hlnstance)  ; 

The  call-back  function  receives  a  far  pointer  to  the  particular  LOGFONT  structure 
that  you  can  use  to  create  this  particular  font,  a  far  pointer  to  the  TEXTMETRIC  structure 
that  will  be  obtained  when  you  select  this  font  into  the  device  context,  a  short  integer  that 
indicates  the  type  of  the  font,  and  a  pointer  to  programmer-supplied  data  specified  in  the 
EnumFonts  call.  (This  last  parameter  simply  provides  a  clean  way  of  passing  information 
to  the  call-back  function  without  using  global  data.) 

Windows  will  continue  calling  the  call-back  function  until  all  the  fonts  are  enumer¬ 
ated  or  until  the  function  returns  0. 

The  nFontType  parameter  to  the  EnumFunction  call-back  function  indicates  the  type 
of  the  font: 


0 

6 

5 

0 

3 

0 

0 

0 

|  Raster  font  if  1 
Scalable  font  if  0 

__  Device-based  font  if  1 
GDI  font  if  0 

_ TrueType  font  if  1 

Non-TrueType  font  if  0 


701 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


You  can  use  the  identifiers  RASTER_FONTTYPE  (which  equals  1)  to  determine  if  the  font 
is  raster  or  scalable,  DEVICE_FONTTYPE  (which  equals  2)  to  determine  if  the  font  is 
device  or  GDI,  and  TRUETYPE_FONTTYPE  (which  equals  4)  to  determine  if  the  font 
is  TrueType.  For  GDI  fonts,  these  are  the  values  you’ll  see: 

Raster:  00000001 

Stroke:  00000000 

TrueType:  00000100 

For  raster  fonts  with  the  low  bit  set  to  1,  the  call-back  function  will  be  called  once  for 
each  available  font  size.  You  can  later  take  the  logical  font  structure  you  get  and  pass  it  to 
CreateFontlndirect.  For  stroke  and  TrueType  fonts  (low  bit  0),  the  call-back  function  is 
called  only  once  for  each  font,  and  you’ll  need  to  set  the  If  Height  Field  of  the  LOGFONT 
structure  before  calling  CreateFontlndirect. 

The  FONTLIST  program,  shown  in  Figure  14-9,  uses  EnumFonts  to  obtain  the  fonts 
available  on  either  the  display  or  the  current  printer.  If  no  printer  is  available,  EnumFonts 
displays  nothing  when  the  Printer  option  is  selected  from  the  menu. 

FONTLIST.MAK 

#■ . . 

#  FONTLIST.MAK  make  file 

# 

fontlist.exe  :  fontlist.obj  fontlist.def  fontlist.res 

$(WINLINK)  fontlist,  fontlist,  NUL,  S(WINLIB),  font! 1st 
rc  -t  fontlist.res 

fontlist.obj  :  fontlist. c  fontlist. h 
$ ( W I NCC )  fontlist. c 

fontlist.res  :  fontlist. rc  fontlist. h 
$ ( WI NRC )  fontlist. rc 


FONTLIST.C 


/* . . . - 

FONTLIST.C  --  Font  Enumeration  Program 
(c)  Charles  Petzold,  1992 
.  . */ 


#include  <windows.h> 
#include  <string.h> 


Figure  1 4-9.  The  FONTLIST program. 


(continued) 
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♦include  <memory.h> 

♦include  "fontl ist.h" 

♦define  min(a.b)  (((a)  <  (b))  ?  (a)  :  (b)) 

♦define  max(a,b)  (((a)  >  (b))  ?  (a)  :  (b)) 

typedef  struct 
{ 

GLOBALHANDLE  hGMem  ; 
short  nCount  ; 

} 

ENUMER  ; 

typedef  struct 
{ 

short  nFontType  ; 

LOGFONT  If  ; 

TEXTMETRIC  tm  ; 

} 

FONT  ; 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

int  FAR  PASCAL  .export  EnumAl 1  Faces  (LPLOGFONT,  LPTEXTMETRI C ,  short, 

ENUMER  FAR  *)  ; 

int  FAR  PASCAL  .export  EnumAl 1  Fonts  (LPLOGFONT,  LPTEXTMETRIC,  short, 

ENUMER  FAR  *)  ; 

char  szAppName[]  =  "FontList"  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  !  CS.VREDRAW  ; 

wndclass. IpfnWndProc  =  WndProc  ; 
wndclass. cbClsExtra  =  0  ; 
wndclass. cbWndExtra  =  0  ; 
wndclass. hlnstance  =  hlnstance  ; 

wndclass. hlcon  =  Loadlcon  (NULL,  IDI.APPLICATION)  ; 

wndclass. hCursor  =  LoadCursor  (NULL,  I DC_ARR0W)  ; 

wndclass. hbrBackground  =  GetStockObject  (WHITE.BRUSH)  ; 
wndclass. IpszMenuName  =  szAppName  ; 
wndclass. lpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 


(continued) 
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hwnd  =  CreateWindow  (szAppName,  "Font  Enumeration", 

WS_OVERLAPP EDWIN DOW  !  WS.VSCROLL, 

CWJJSEDEFAULT,  CW_USEDEFAU LT , 

CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

int  FAR  PASCAL  .export  EnumAllFaces  (LPLOGFONT  lplf,  LPTEXTMETRIC  lptm, 

short  nFontType,  ENUMER  FAR  *enumer) 

{ 

LPSTR  lpFaces  ; 

if  (NULL  ==  GlobalReAlloc  (enumer->hGMem, 

(DWORD)  LF.FACESIZE  *  (1  +  enumer->nCount) , 
GMEM.MOVEABLE) ) 

return  0  ; 

lpFaces  =  G1 obal Lock  (enumer->hGMem)  ; 
lstrcpy  (lpFaces  +  enumer->nCount  *  LF.FACESIZE, 

(char  FAR  *)  1  pi f->l f FaceName)  ; 

GlobalUnlock  (enumer->hGMem)  ; 
enumer->nCount  ++  ; 
return  1  ; 

} 

int  FAR  PASCAL  .export  EnumAllFonts  (LPLOGFONT  lplf,  LPTEXTMETRIC  lptm, 

short  nFontType,  ENUMER  FAR  *enumer) 

{ 

FONT  FAR  *font  ; 

if  (NULL  ==  GlobalReAlloc  (enumer->hGMem, 

(DWORD)  sizeof  (FONT)  *  (1  +  enumer->nCount) , 
GMEM.MOVEABLE) ) 

return  0  ; 

font  =  (FONT  FAR  *)  Global  Lock  (enumer->hGMem)  +  enumer->nCount  ; 
font->nFontType  =  nFontType  ; 

.fmemcpy  (&font->lf,  lplf,  sizeof  ( LOGFONT) )  ; 

.fmemcpy  (&font->tm,  lptm,  sizeof  (TEXTMETRIC) )  ; 


(continued) 
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GlobalUnlock  (enumer->hGMem)  ; 
enumer->nCount  ++  ; 
return  1  ; 

} 

void  Display  (HDC  hdc,  short  cxChar,  short  cyChar,  FONT  FAR  *lpfont) 
{ 

static  FONT  f  : 


static 

char 

*szYN 

[] 

= 

{ 

"No", 

"Yes"  }  ; 

static 

char 

*szOP 

[] 

= 

{ 

"Default", 

"String",  " 

Char", 

"Stroke" 

} 

static 

char 

*szCP 

[] 

= 

{ 

"Default", 

"Char", 

Stroke", 

••?????" 

} 

static 

char 

*szQU 

[] 

= 

{ 

"Draft", 

"Default",  " 

Proof", 

"?????" 

} 

static 

char 

*szPl 

[] 

= 

{ 

"Default", 

"Fixed",  " 

Variable" 

"?????" 

} 

static 

char 

*szP2 

[] 

= 

{ 

"Fixed", 

"Variable" 

}  ; 

static 

char 

*szFA 

[] 

= 

{ 

"Don't  Care", 

"Roman", 

"Swiss", 

,  "Modern" 

"Script", 

"Decorative" 

"?????" 

"?????" 

static 

char 

*szVR 

□ 

= 

{ 

"Scalable", 

"Raster" 

’}  ; 

static 

char 

*szGD 

[] 

= 

{ 

"GDI", 

"Device" 

}  : 

static 

char 

*szSC 

□ 

= 

{ 

"Non-TrueType" 

,  "TrueType" 

}  ; 

static  struct 
{ 

short  x  ; 
short  y  ; 
char  *szFmt  ; 
int  *pData  ; 
} 

shorts  []  = 

{ 


1. 

1,  "LOGFONT", 

NULL, 

i. 

p  t»  ti 

NULL, 

1, 

3,  "Height: 

%10d". 

&f .If .lfHeight, 

1. 

4,  "Width: 

%10d", 

&f .If .IfWidth, 

i, 

5,  "Escapement: 

%10d". 

&f .If .IfEscapement, 

1. 

6.  "Orientation: 

%10d" , 

&f  .If.lfOrientation, 

i. 

7,  "Weight: 

%10d", 

&f .If .lfWeight, 

28, 

1,  "TEXTMETRIC", 

NULL, 

28. 

2,  " . ", 

NULL, 

28, 

3,  "Height: 

%5d" , 

&f .tm.tmHeight, 

28, 

4,  "Ascent: 

%5d". 

&f .tm.tmAscent, 

28, 

5,  "Descent: 

%5d", 

&f .tm.tmDescent, 

28, 

6,  "Int.  Leading; 

:  %5d". 

&f .tm.tmlnternal Leading, 

28. 

7,  "Ext.  Leading: 

:  %5d", 

&f .tm.tmExternal Leading, 

28, 

8.  "Ave.  Width: 

%5d". 

&f . tm. tmAveCharWi dth , 

28, 

9,  "Max.  Width: 

%5d", 

&f . tm.tmMaxCharWidth, 

28, 

10,  "Weight: 

%5d". 

&f .tm.tmWeight, 

51, 

10,  "Overhang: 

%10d", 

&f .tm.tmOverhang, 

51, 

11,  "Digitized  X: 

%10d", 

&f . tm . tmDi gi ti zedAspectX , 

51, 

}  ; 

12,  "Digitized  Y: 

%10d". 

&f . tm. tmDi gi ti zedAspectY , 

(continued) 
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static  struct 
{ 

short  x  ; 
short  y  ; 
char  *szFmt  ; 

BYTE  *pData  ; 

} 

bytes  []  = 

{ 

51.  3,  "First  Char: 
51.  4,  "Last  Char: 

51,  5,  "Default  Char: 

51.  6,  "Break  Char: 

}  ; 


%10d",  &f .tm.tmFirstChar, 
%10d" ,  &f .tm.tmLastChar, 
%10d",  &f .tm.tmDefaul tChar, 
%10d",  &f .tm.tmBreakChar, 


static  struct 
{ 

short  x  ; 
short  y  ; 
char  *szFmt  ; 
BYTE  *PData  ; 
char  **szArray  ; 
short  sAnd  ; 
short  sShift  : 

} 

strings  []  = 

{ 


1. 

8,  "Italic: 

%10s". 

&f .If .lfltalic, 

szYN, 

1, 

1, 

9,  "Underline: 

X10s". 

&f .If .lfUnderl ine, 

szYN, 

1, 

1. 

10,  "Strike-Out: 

%10s". 

&f .If .lfStrikeOut, 

szYN, 

1, 

1. 

11,  "Char  Set: 

%10s", 

&f .If .lfCharSet, 

NULL, 

0, 

1. 

12,  "Out  Prec: 

%10s". 

&f .If .lfOutPrecision, 

szOP, 

3. 

1. 

13,  "Clip  Prec: 

%10s", 

&f .If . 1 fCl i pPreci si  on , 

szCP, 

3, 

1. 

14,  "Quality: 

X10s". 

&f .If .lfQuality, 

szQU, 

3. 

1. 

15.  "Pitch: 

X10s", 

&f .If .lfPitchAndFamily, 

szPl, 

3, 

1. 

16,  "Family: 

%10s". 

&f .If .IfPitchAndFamily, 

szFA, 

0x70, 

28, 

11,  "Italic: 

%5s" , 

&f .tm.tmltal ic. 

szYN, 

1. 

28. 

12,  "Underline: 

%5s” , 

&f .tm.tmUnderl  ined, 

szYN, 

1, 

28, 

13,  "Strike-Out: 

%5s". 

&f . tm.tmStruckOut, 

szYN, 

1, 

51. 

7,  "Pitch: 

%10s", 

&f .tm.tmPitchAndFamily, 

szP2, 

1, 

51. 

8,  "Family: 

%10s", 

&f .tm.tmPi tchAndFamily, 

szFA, 

0x70, 

51, 

9,  "Char  Set: 

%10s". 

&f .tm.tmCharSet , 

NULL, 

0. 

28. 

15,  "Font  Type: 

%s". 

(BYTE  *)  &f .nFontType, 

szVR, 

1, 

50, 

15,  "%s", 

(BYTE  *)  &f. nFontType, 

szGD, 

2, 

58. 

}  ; 

15,  "%s". 

(BYTE  *)  &f. nFontType, 

szSC, 

4, 

1. 

2 


char  *szCharSet,  szBuffer  [80]  ; 
int  i  ; 

_fmemcpy  (&f,  lpfont,  sizeof  (FONT))  ; 


(continued) 
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for  (i  =  0  ;  i  <  sizeof  shorts  /  sizeof  shorts  [0]  ;  i++) 

TextOut  (hdc,  cxChar  *  shorts[i].x,  cyChar  *  shorts [i ] .y ,  szBuffer, 
wsprintf  (szBuffer,  shorts[i].szFmt, 

*shorts[i].pData))  ; 

for  ( i  =  0  ;  i  <  sizeof  bytes  /  sizeof  bytes  [0]  ;  i++) 

TextOut  (hdc,  cxChar  *  bytes[i].x,  cyChar  *  bytes [i ] .y ,  szBuffer, 
wsprintf  (szBuffer,  bytes [ i ] .szFmt, 

*bytes[i].pData))  ; 


for 


(1  = 
{ 

if 


i  <  sizeof  strings  7  sizeof  strings  [0]  ;  i++) 


(strings[i].szArray  ==  NULL) 

{ 

switch  (*strings[i].pData) 

{ 

case  ANSI_CHARSET  : 

//  Character  set 

szCharSet  =  "ANSI"  ; 

break 

case  SYMBOL_CHARSET  : 

szCharSet  =  "Symbol"  ; 

break 

case  SHI  FT J I S_CHARS ET  : 

szCharSet  =  "Shift  JIS"  ; 

break 

case  OEM_CHARSET  : 

szCharSet  =  "OEM"  ; 

break 

default  : 

szCharSet  =  "?????"  ; 

break 

} 

TextOut  (hdc,  cxChar  *  strings[i].x, 

cyChar  *  strings[i].y,  szBuffer, 
wsprintf  (szBuffer,  strings[i] .szFmt, 
( LPSTR)  szCharSet))  ; 


else 


} 


TextOut  (hdc,  cxChar  *  strings[i ] .x, 

cyChar  *  strings[i].y,  szBuffer, 
wsprintf  (szBuffer,  stri ngs[i ] . szFmt, 

(LPSTR)  ((strings[i].szArray) 

[(*strings[i].pData  &  stri ngs[i ] . sAnd )  » 
stri ngs[i ] . sShi ft] ) ) )  ; 


TextOut  (hdc,  cxChar,  cyChar  *  17,  szBuffer, 

wsprintf  (szBuffer,  "Face  Name:  %10s" 
(LPSTR)  f.lf .IfFaceName))  ; 

} 


HDC  GetPrinterIC  0 
{ 

char  szPrinter  [64]  ; 

char  *szDevice,  *szDriver,  *szOutput  ; 

GetProfileString  ("windows",  "device",  "",  szPrinter,  64)  ; 
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if  (NULL  !=  (szDevice  =  strtok  (szPrinter,  ","  ))  && 

NULL  !=  (szDriver  =  strtok  (NULL,  ",  "))  && 

NULL  !=  (szOutput  =  strtok  (NULL.  ",  "))) 


return  CreateIC  (szDriver,  szDevice,  szOutput,  NULL)  ; 

return  NULL  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  BOOL  bHavelnfo  =  FALSE  ; 


static  ENUMER 

static  FARPROC 

static  short 

static  WORD 

HANDLE 

HDC 

HFONT 

HMENU 

FONT  FAR 

LPSTR 

PAINTSTRUCT 

short 

TEXTMETRIC 


enumerl,  enumer2  ; 

lpfnEnumAll Faces,  lpfnEnumAl 1  Fonts  ; 

cxChar,  cyChar,  nCurrent  ; 

wCurrentDC  =  IDM.SCREEN  ; 

hlnstance  ; 

hdc  ; 

hFont  ; 

hMenu  ; 

*font  ; 
lpFaces  ; 
ps  ; 
i  ; 
tm  ; 


switch  (message) 

{ 

case  WM.CREATE  : 

hlnstance  =  ( ( LPCREATESTRUCT)  lParam)->  hlnstance  ; 
lpfnEnumAll Faces  =  MakeProcInstance  ((FARPROC)  EnumAll Faces, 

hlnstance)  ; 

lpfnEnumAll Fonts  =  MakeProcInstance  ((FARPROC)  EnumAll Fonts, 

hlnstance)  ; 

hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc,  GetStockObject  (SYSTEM.FIXED.FONT) )  ; 

GetTextMetrics  (hdc,  ( LPTEXTMETRIC)  &tm)  ; 

cxChar  =  tm. tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm.tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 
return  0  ; 

case  WM.COMMAND  : 

if  (wParam  ==  IDM.EXIT) 

{ 

SendMessage  (hwnd,  WM.CLOSE,  0,  0L)  ; 
return  0  ; 

) 


(continued) 
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else  if  (wParam  ==  wCurrentDC) 
return  0  ; 

hMenu  =  GetMenu  (hwnd)  ; 

CheckMenuItem  (hMenu,  wCurrentDC,  MFJJNCHECKED)  ; 
CheckMenuItem  (hMenu,  wCurrentDC  =  wParam,  MF_CHECKED)  ; 

//  fall  through 

case  WMJ3EVM0DECHANGE  : 
case  WM_FONTCHANGE  : 

bHavelnfo  =  FALSE  ; 

InvalidateRect  (hwnd,  NULL,  TRUE)  j 
return  0  ; 

case  WM_PAI NT  : 

if  ( IbHavelnfo) 

{ 

if  (enumer2.hGMem) 

GlobalFree  (enumer2.hGMeni)  ; 

enumerl.hGMem  =  GlobalAlloc  (GHND,  1L)  ; 
enumerl.nCount  =  0  ; 

enumer2.hGMem  =  GlobalAlloc  (GHND,  1L)  ; 
enumer2.nCount  =  0  ; 

if  (NULL  ==  enumerl.hGMem  !!  NULL  ==  enumer2.hGMem) 
goto  MEM0RY_ERR0R  ; 

if  (wCurrentDC  ==  IDM.SCREEN) 

hdc  =  CreateIC  ( "DISPLAY” ,  NULL,  NULL,  NULL)  ; 

else 

hdc  =  GetPri nterIC  0  ; 

if  (hdc) 

{ 

if  (0  ==  EnumFonts  (hdc,  NULL,  1 pfnEnumAl 1  Faces , 

( LPSTR)  Senumerl)) 

goto  MEMORY.ERROR  ; 

lpFaces  =  Global  Lock  (enumerl.hGMem)  ; 

for  ( i  =0  ;  i  <  enumerl.nCount  ;  i++) 
if  (0  ==  EnumFonts  (hdc, 

lpFaces  +  i  *  LF.FACESIZE, 

1 pfnEnumAl 1  Fonts, 

(LPSTR)  &enumer2) ) 
goto  MEMORY.ERROR  ; 
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GlobalUnlock  (enumerl.hGMem)  ; 
enumer2.nCount--  ; 

DeleteDC  (hdc)  ; 
bHavelnfo  =  TRUE  ; 

} 

G1 obal Free  (enumerl.hGMem)  ; 

SetScroll Range  (hwnd,  SB_VERT .  0,  enumer2.nCount ,  FALSE)  ; 
SetScrollPos  (hwnd,  SB_VERT,  nCurrent  =  0,  TRUE)  ; 

} 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

if  (bHavelnfo) 

{ 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

font  =  (FONT  FAR  *)  Global  Lock  (enumer2.hGMem)  +  nCurrent  ; 
Display  (hdc,  cxChar,  cyChar,  font)  ; 

hFont  =  SelectObject  (hdc,  CreateFontlndi rect  (&font->lf))  ; 

TextOut  (hdc,  1  *  cxChar,  19  *  cyChar, 

"AaBbCcDdEeFfGgHhli JjKkLl MmNnOoPpQqRrSsTtUuVvWwXxYyZz" , 
52)  ; 

GlobalUnlock  (enumer2. hGMem)  ; 

DeleteObject  (SelectObject  (hdc,  hFont))  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_KEYDOWN  : 
switch  (wParam) 

{ 

case  VK_H0ME  : 

SendMessage  (hwnd,  WM.VSCROLL,  SB_T0P,  0L)  ; 
break  ; 
case  VK.END  : 

SendMessage  (hwnd,  WM_VSCROLL,  SB.BOTTOM,  0L)  ; 
break  ; 

case  VK.LEFT  : 
case  VK_UP  : 
case  VK_PRI0R  : 

SendMessage  (hwnd,  WM.VSCROLL,  SB.LINEUP,  0L)  ; 
break  ; 

case  VK.RIGHT  : 
case  V K_D0WN  : 
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case  VK_NEXT  : 

SendMessage  (hwnd,  WM_VSCROLL,  SB_LI NEDOWN ,  0L)  ; 
break  ; 
default  : 

return  0  ; 

} 

return  0  ; 

case  WM_VSCROLL  : 

switch  (wParam) 

{ 

case  SB_T0P  : 

nCurrent  =  0  ;  • 

break  ; 

case  SB_B0TT0M  : 

nCurrent  =  enumer2.nCount  ; 
break  ; 

case  SB_LINEUP  : 
case  SB.PAGEUP  : 
nCurrent--  ; 
break  ; 

case  SB_L I NEDOWN  : 
case  SB_PAGEDOWN  : 
nCurrent++  ; 
break  ; 

case  S B_T HUMBPOSITION  : 

nCurrent  =  LOWORD  (lParam)  ; 
break  ; 
default  : 

return  0  ; 

} 

nCurrent  =  min  (max  (0,  nCurrent),  enumer2.nCount)  ; 

SetScrollPos  (hwnd,  SB_VERT,  nCurrent,  TRUE)  ; 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 

return  0  ; 

MEM0RY_ERR0R  : 

Me'ssageBox  (hwnd,  "Cannot  allocate  memory,  must  end.", 
szAppName,  MB_0K  !  MB.ICONSTOP  !  MB_SY STEMMODAL )  ; 

//  fall  through 

case  WM.CLOSE  : 

DestroyWindow  (hwnd)  ; 

return  0  ; 

case  WM_DESTROY  : 

PostQui tMessage  (0)  ; 

return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  lParam)  ; 
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FONTLIST.RC 

/* . - 

FONTLIST.RC  resource  script 
.  */ 

#include  "fontlist.h" 

FontList  MENU 

{ 

POPUP  "&Device" 

{  * 

MENUITEM  "&Screen",  IDM.SCREEN,  CHECKED 
MENUITEM  "&Printer",  I DM_PRI NTER 
MENUITEM  SEPARATOR 
MENUITEM  "E&xi t" ,  IDM.EXIT 
} 

} 


FONTLIST.H 

j  if - - - - - - - - - 

FONTLIST.H  header  file 

. --*/ 

^define  IDM_SCREEN  1 
#define  I DM_PRI NTER  2 
^define  IDM_EXIT  3 


FONTLIST.DEF 


FONTLIST. DEF  module  definition  file 


NAME  FONTLIST 

DESCRIPTION  'Font  Enumeration  Program  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 
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FONTLIST  uses  two  separate  call-back  functions  to  enumerate  the  fonts.  The  first, 
called  EnumAllFaces,  accumulates  the  typeface  names.  The  second,  EnumAllFonts,  ac¬ 
cumulates  all  the  sizes  for  each  typeface  name.  The  program  uses  global  memory  blocks  to 
store  this  information.  If  FONTLIST  runs  out  of  memory  space,  the  program  aborts  after 
displaying  a  message  box. 

After  FONTLIST  is  finished  getting  the  fonts,  it  displays  both  the  logical  font  structure 
and  the  text  metrics  structure  for  each  font,  one  font  per  screen,  with  a  sample  line  of  text 
at  the  bottom  of  the  screen.  You  can  move  through  the  fonts  using  the  vertical  scroll  bar  or 
the  cursor  keys.  A  large  part  of  the  program  (the  Display  function)  is  devoted  to  formatting 
the  information  for  display.  Figure  14-10  shows  a  typical  FONTLIST  screen. 

FONTLIST  will  list  all  installed  fonts.  You’ll  note  from  the  “Digitized  X”  and  “Digi¬ 
tized  Y”  fields  that  some  of  the  raster  fonts  may  not  match  the  aspect  ratio  of  the  video  dis¬ 
play  and  may  look  a  little  funny.  When  using  the  EnumFonts  function  in  a  real  application 
to  obtain  raster  fonts,  you  should  first  obtain  the  resolution  of  the  device  in  logical  pixels 
per  inch  by  using  the  GetDeviceCaps  function  with  the  LOGPIXELSX  and  LOGPIXELSY 
parameters.  You  should  then  reject  any  font  in  which  the  tmDigitizedAspectX  and 
tmDigitizedAspectY v alues  of  the  TEXTMETRIC  function  do  not  match  these  values. 


||  Device 

Height : 

36 

Height : 

36 

First  Char: 

30 

Width: 

14 

Ascent : 

29 

Last  Char: 

255 

Escapement : 

0 

Descent : 

7 

DeFault  Char: 

31 

Orientation : 

0 

Int.  Leading 

:  4 

Break  Char: 

32 

Weight : 

400 

Ext.  Leading 

:  1 

Pitch : 

Uariable 

Italic : 

Ves 

Aue.  Width: 

14 

Family : 

Swiss 

Underline : 

No 

Max.  Width: 

38 

Char  Set: 

ANSI 

Strike-Out: 

No 

Weight : 

400 

Overhang : 

0 

Char  Set: 

ANSI 

Italic : 

Ves 

Digitized  X: 

96 

Out  Prec: 

Stroke 

Underline : 

No 

Digitized  V: 

96 

Clip  Prec: 

Stroke 

Strike-Out : 

No 

Quality : 

DeFault 

Pitch: 

Uariable 

Font  Type: 

Scalable 

GDI  TrueType 

Family : 

Swiss 

Face  Name: 

Arial 

A  aBbCcDdE  eFfGgHhliJjKkUMmNn  O  oPp  Q  <1 


Program  Fie  Manager 
Manager 


Figure  14-10.  A  typical  FONTLIST  display. 
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FONTLIST  intercepts  the  WM_DEVMODECHANGE  message  (which  indicates  a 
change  of  printer)  and  the  WM_FONTCHANGE  message  (which  indicates  a  change  in  the 
font  resources  available).  You  can  use  FONTLIST  to  examine  the  fonts  available  on  differ¬ 
ent  printers  by  changing  the  current  printer  using  the  Control  Panel  program.  If  you  choose 
to  list  the  fonts  for  the  current  printer,  you  may  wonder  how  FONTLIST  is  able  to  display  a 
device  printer  font  at  the  bottom  of  the  client  area.  Although  FONTLIST  shows  the  logical 
font  and  text  metrics  structures  for  device  printer  fonts,  the  sample  text  is  a  normal  GDI 
font  that  Windows  picks  based  on  the  logical  font  structure  for  the  printer  font.  It’s  the 
closest  approximation  of  the  printer  font  that  Windows  can  display  on  the  screen. 


FORMATTING  TEXT 

Now  that  you  know  how  to  determine  the  fonts  available  on  a  particular  device,  how  to 
create  a  font  and  select  it  into  the  device  context,  and  how  to  determine  the  sizes  and  char¬ 
acteristics  of  the  fonts,  it’s  time  to  try  your  hand  at  text  formatting.  The  process  involves 
placing  each  line  of  text  within  margins  in  one  of  four  ways:  aligned  on  the  left  margin, 
aligned  on  the  right  margin,  centered  between  the  margins,  or  justified — that  is,  running 
from  one  margin  to  the  other,  with  equal  spaces  between  the  words.  For  the  first  three  jobs, 
you  can  use  the  DrawText  function  with  the  DT_WORDBREAK  parameter,  but  this  ap¬ 
proach  has  limitations.  For  instance,  you  can’t  determine  what  part  of  the  text  DrawText 
was  able  to  fit  within  the  rectangle.  DrawText  is  convenient  for  some  simple  jobs,  but  for 
more  complex  formatting  tasks,  you’ll  probably  want  to  employ  TextOut. 

One  of  the  most  useful  functions  for  working  with  text  is  GetTextExtent.  This  func¬ 
tion  tells  you  the  width  and  height  of  a  character  string  based  on  the  current  font  selected 
in  the  device  context: 

dwExtent  =  GetTextExtent  (hdc,  IpString,  nCo'unt)  ; 

The  width  of  the  text  in  logical  units  is  in  the  low  word  of  dwExtent ,  and  the  height  of  the 
text  in  logical  units  is  in  the  high  word.  Although  you  can  also  obtain  the  text  height  from 
the  tmHeight  field  of  the  TEXTMETRIC  structure,  the  TEXTMETRIC  width  is  inadequate 
when  you’re  working  with  variable-pitch  fonts  or  with  italic  or  boldface  text. 

Breaking  text  into  lines  involves  searching  for  break  characters.  In  theory,  you  should 
determine  the  font’s  break  character  from  the  tmBreakChar  field  of  the  TEXTMETRIC 
structure,  but  you  can  also  simply  assume  that  it’s  the  space  character  (ASCII  number  32). 
In  theory,  you  should  also  use  the  AnsiNext  and  AnsiPrev  functions  to  step  through  the 
string,  but  you’ll  get  better  performance  if  you  use  normal  C  pointer  arithmetic.  (Of  course, 
if  you  hope  to  eventually  convert  your  programs  to  languages  that  use  multibyte  character 
sets,  you  had  best  follow  these  “in  theory”  rules  right  from  the  start.) 
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One-Line  Text  Alignment 

I’ll  begin  with  an  example  using  one  line  of  text.  Let’s  say  that  you  have  selected  a  font  into 
your  device  context  and  now  want  to  write  the  text: 

char  *szText  []  =  "Hello,  how  are  you?"  ; 

You  want  the  text  to  start  at  the  vertical  coordinate  yStart ,  within  margins  set  by  the  coor¬ 
dinates  xLeft  and  xRight.  Your  job  is  to  calculate  the  xStart  value  for  the  horizontal  coordi¬ 
nate  where  the  text  begins.  This  job  would  be  considerably  easier  if  the  text  were 
displayed  using  a  fixed-pitch  font,  but  that’s  not  the  general  case. 

First,  you  get  the  text  extents  of  the  string: 

dwExtent  =  GetTextExtent  (hdc,  szText,  strlen  (szText))  ; 

If  the  low  word  of  dwExtent  is  larger  than  ( xRight  -  xLeft),  then  the  line  is  too  long  to  fit 
within  the  margins.  Let’s  assume  it  can  fit. 

To  align  the  text  on  the  left  margin,  you  simply  set  xStart  equal  to  xLeft  and  then  write 
the  text: 

TextOut  (hdc,  xStart,  yStart,  szText,  strlen  (szText))  ; 

This  is  easy.  You  can  now  add  the  high  word  of  dwExtent  to  yStart ,  and  you’re  ready  to 
write  the  next  line  of  text. 

To  align  the  text  on  the  right  margin,  you  use  this  formula  for  xStart : 
xStart  =  xRight  -  LOWORD  (dwExtent)  ; 

To  center  the  text  between  the  left  and  right  margins,  use  this  formula: 
xStart  =  (xLeft  +  xRight  -  LOWORD  (dwExtent))  /  2  ; 

Now  here’s  the  tough  job — to  justify  the  text  within  the  left  and  right  margins.  The 
distance  between  the  margins  is  ( xRight  -  xLeft).  Without  justification,  the  text  is 
LOWORD  {dwExtent)  wide.  The  difference  between  these  two  values,  which  is: 

xRight  -  xLeft  -  LOWORD  (dwExtent) 

must  be  equally  distributed  among  the  three  space  characters  in  the  character  string.  It 
sounds  like  a  terrible  job,  but  it’s  not  too  bad.  To  do  it,  you  call: 

SetTextJusti fi cati on  (hdc,  xRight  -  xLeft  -  LOWORD  (dwExtent),  3) 

The  second  parameter  is  the  amount  of  space  that  must  be  distributed  among  the  space 
characters  in  the  character  string.  The  third  parameter  is  the  number  of  space  characters — 
in  this  case,  3. 
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Now  set  xStart  equal  to  xLeft  and  write  the  text  with  TextOut: 

TextOut  (hdc,  xStart,  yStart,  szText,  strlen  (szText))  ; 

The  text  will  be  justified  between  the  xLeft  and  xRight  margins. 

Whenever  you  call  SetTextJustification,  it  accumulates  an  error  term  if  the  amount  of 
space  doesn’t  distribute  evenly  among  the  space  characters.  This  error  term  will  affect  sub¬ 
sequent  GetTextExtent  calls.  Each  time  you  start  a  new  line,  you  should  clear  out  the  error 
term  by  calling: 

SetTextJustification  (hdc.  0,  0)  ; 

Working  with  Paragraphs 

If  you’re  working  with  a  whole  paragraph,  you  have  to  start  at  the  beginning  and  scan 
through  the  string  looking  for  blanks.  Every  time  you  encounter  a  blank,  you  call  GetText¬ 
Extent  to  determine  if  the  text  still  fits  between  the  left  and  right  margins.  When  the  text 
exceeds  the  space  allowed  for  it,  you  backtrack  to  the  previous  blank.  Now  you  have  deter¬ 
mined  the  character  string  for  the  line.  If  you  want  to  justify  the  line,  call  SetTextJustifica¬ 
tion  and  TextOut ,  clear  out  the  error  term,  and  proceed  to  the  next  line. 

The  JUSTIFY  program,  shown  in  Figure  14-11,  does  this  job  for  the  first  paragraph  of 
Herman  Melville’s  Moby  Dick.  You  choose  a  screen  font,  and  the  Alignment  menu  lets  you 
align  the  text  left  or  right,  center  it,  or  justify  it.  Figure  14-12  (on  page  724)  shows  a  typical 
JUSTIFY  screen. 


JUSTIFY.MAK 

# 

#  JUSTIFY.MAK  make  file 


justify.exe  :  justify. obj  justify.def  justify. res 

$(WINLINK)  justify,  justify.  NUL.  $(WINLIB),  justify 
rc  -t  justify. res 

justify. obj  :  justify. c  justify.h 
$ ( W I NCC )  justify. c 

justify. res  :  justify. rc  justify. asc  justify.h 
$(WINRC)  justify. rc 


Figure  14-11.  The  JUSTIFY  program. 
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JUSTIFY.C 


/* . - . - 

JUSTIFY.C  --  Justified  Type  Program 

(c)  Charles  Petzold,  1992 
.  . */ 


#include  <windows.h> 

#include  <commdlg.h> 

#include  "justify. h" 
typedef  unsigned  int  UINT  ; 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "Justify"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. IpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 


CS.HREDRAW 
WndProc  ; 

0  : 


CS_V  REDRAW 


wndclass. IpszClassName  =  szAppName  ; 


hlnstance  ; 

Loadlcon  (NULL,  IDI .APPLICATION) 
LoadCursor  (NULL,  IDC.ARR0W)  ; 
GetStockObject  (WHITE.BRUSH)  ; 
szAppName 


RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Justified  Type", 
WS.OVERLAPP EDWIN DOW, 
CW.USEDEFAULT,  CW.USEDEFAULT, 
CW.USEDEFAULT,  CW.USEDEFAULT, 
NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 


(continued) 
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while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  DrawRuler  (HDC  hdc,  RECT  *prc) 

{ 

static  short  nRuleSize  [16]  =  {  360,  72,  144,  72,  216,  72,  144,  72, 

288,  72,  144,  72,  216,  72,  144,  72  }  ; 

short  i ,  j  ; 

POINT  ptClient  ; 

SaveDC  (hdc)  ; 

//  Set  Logical  Twips  mapping  mode 

SetMapMode  (hdc,  MM_ANIS0TR0PIC)  ; 

SetWindowExt  (hdc,  1440,  1440)  ; 

SetViewportExt  (hdc,  GetDeviceCaps  (hdc,  LOGPIXELSX), 

GetDeviceCaps  (hdc,  LOGPIXELSY) )  ; 

//  Move  the  origin  to  a  half  inch  from  upper  left 

SetWindowOrg  (hdc,  -720,  -720)  ; 

//  Find  the  right  margin  (quarter  inch  from  right) 

ptClient. x  =  prc->right  ; 
ptClient. y  =  prc->bottom  ; 

DPtoLP  (hdc,  &ptCl i ent ,  1)  ; 
ptClient. x  -=  360  ; 

//  Draw  the  rulers 

MoveTo  (hdc,  0,  -360)  ; 

LineTo  (hdc,  ptClient. x,  -360)  ; 

MoveTo  (hdc,  -360,  0)  ; 

LineTo  (hdc,  -360,  ptClient. y)  ; 

for  (i  =  0,  j  =  0  ;  i  <=  ptClient. x  ;  i  +=  1440  /  16,  j++) 

{ 

MoveTo  (hdc,  i,  -360)  ; 

LineTo  (hdc,  i,  -360  -  nRuleSize  [j  %  16])  ; 

} 

for  (i  =  0,  j  =  0  ;  i  <=  ptClient.y  ;  i  +=  1440  /  16,  j++) 

{ 

MoveTo  (hdc,  -360,  i )  ; 

LineTo  (hdc,  -360  -  nRuleSize  [j  %  16],  i)  ; 

} 
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RestoreDC  (hdc,  -1)  ; 

} 

void  Justify  (HDC  hdc,  LPSTR  lpText,  RECT  *prc,  short  nAlign) 

{ 

DWORD  dwExtent  ; 

LPSTR  lpBegin,  IpEnd  ; 

short  xStart,  yStart,  nBreakCount  ; 

yStart  =  prc->top  ; 

do  //  For  each  text  line 

{ 

nBreakCount  =  0  ; 

while  (*lpText  ==  *  ')  //  skip  over  leading  blanks 

lpText++  ; 
lpBegin  =  lpText  ; 

do  //  until  the  line  is  known 

{ 

IpEnd  =  TpText  ; 

while  ( *1 pText  !=  '\0'  &&  *lpText++  !=''); 
if  (*1 pText  ==  ' \0 ' ) 
break  ; 

//  For  each  space,  calculate  extents 

nBreakCount++  ; 

SetTextJustification  (hdc,  0,  0)  ; 

dwExtent  =  GetTextExtent  (hdc,  lpBegin,  lpText  -  lpBegin  -  1)  ; 
} 

while  ( ( i n t )  LOWORD  (dwExtent)  <  (prc->right  -  prc->left))  ; 
nBreakCount--  ; 

while  (*(lpEnd  -  1)  ==  '  ')  //  Eliminate  trailing  blanks 

{ 

IpEnd--  ; 
nBreakCount--  ; 

} 

if  (*lpText  ==  '\0'  !!  nBreakCount  <=  0) 

IpEnd  =  lpText  ; 

SetTextJustification  (hdc,  0,  0)  ; 

dwExtent  =  GetTextExtent  (hdc,  lpBegin,  IpEnd  -  lpBegin)  ; 

switch  (nAlign)  //  Use  alignment  for  xStart 

{ 

case  I DM_LE FT  : 

xStart  =  prc->left  ; 
break  ; 
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case  I DM_RI GHT  : 

xStart  =  prc ->ri ght  -  LOWORD  (dwExtent)  ; 
break  ; 

case  IDM_CENTER  : 

xStart  =  (prc->right  +  prc->left  -  LOWORD  (dwExtent))  /  2  ; 
break  ; 

case  IDM_JUST  : 

if  (*lpText  !=  ' \0 '  &&  nBreakCount  >  0) 

SetTextJustification  (hdc, 

prc->ri ght  -  prc->l eft  -  LOWORD  (dwExtent), 
nBreakCount)  ; 
xStart  =  prc->l eft  ; 
break  ; 

} 

TextOut  (hdc,  xStart,  yStart,  lpBegin,  IpEnd  -  lpBegin)  ; 
yStart  +=  HIWORD  (dwExtent)  ; 
lpText  =  IpEnd  ; 

} 

while  (*lpText  &&  yStart  <  prc->bottom)  ; 

} 

long  FAR  PASCAL  ..export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  CH00SEF0NT  cf  ; 

static  HANDLE  hResource  ; 

static  LOGFONT  If  ; 

static  LPSTR  lpText  ; 

static  short  nAlign  =  IDM_LEFT  ; 

HANDLE  hlnstance  ; 

HDC  hdc  ; 

HMENU  hMenu  ; 

PAINTSTRUCT  ps  ; 

RECT  rcClient  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

//  Initialize  the  CH00SEF0NT  structure 

GetObject  (GetStockObject  (SYSTEM_FONT) ,  sizeof  (LOGFONT), 
(LPSTR)  &lf)  ; 

cf.lStructSize  =  sizeof  (CH00SEF0NT)  ; 

cf.hwndOwner  =  hwnd  ; 
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cf.lpLogFont  =  &lf  ; 

cf. Flags  =  CF_INITTOLOGFONTSTRUCT  !  CF_SCREENFONTS 

!  CF_EFFECTS  ; 

//  Load  the  Text  Resource 

hlnstance  =  ( ( LPCREATESTRUCT)  lParam)->  hlnstance  ; 

hResource  =  LoadResource  (hlnstance, 

FindResource  (hlnstance,  "Ishmael",  "TEXT"))  ; 

IpText  =  LockResource  (hResource)  ; 
return  0  ; 

case  WM.COMMAND  : 

hMenu  =  GetMenu  (hwnd)  ; 

switch  (wParam) 

{ 

case  I DM_F0NT  : 

if  (ChooseFont  (&cf)) 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
break  ; 

case  I DM_LE FT  : 
case  I DM_RI GHT  : 
case  IDM.CENTER  : 
case  IDM_JUST  : 

CheckMenuItem  (hMenu,  nAlign,  MF_UNCHECKED)  ; 
nAlign  =  wParam  ; 

CheckMenuItem  (hMenu,  nAlign,  MF_CH ECKED )  ; 
InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
break  ; 

} 

return  0  ; 
case  WM_PAINT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

GetClientRect  (hwnd,  &rcClient)  ; 

DrawRuler  (hdc,  &rcClient)  ; 

rcClient.left  +=  GetDeviceCaps  (hdc,  LOGPIXELSX)  /  2  ; 

rcClient.top  +=  GetDeviceCaps  (hdc,  LOGPIXELSY)  /  2  ; 

rcClient. right  -=  GetDeviceCaps  (hdc,  LOGPIXELSX)  /  4  ; 

SelectObject  (hdc,  CreateFontlndirect  (&lf))  ; 

SetTextColor  (hdc.  cf .rgbColors)  ; 

Justify  (hdc,  IpText,  &rcClient,  nAlign)  ; 


(continued) 
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DeleteObject  (Sel ectObject  (hdc,  GetStockObject  (SYSTEM_FONT) ) )  ; 
EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

GlobalUnlock  (hResource)  ; 

FreeResource  (hResource)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


JUSTIFY.RC 


/* . 

JUSTIFY.RC  resource  script 

. */ 


//include  "justify. h" 

Ishmael  TEXT  justify. asc 

Justify  MENU 
{ 

POPUP  "&Font" 

{ 

MENUITEM  "&Font. . IDM.FONT 
} 

POPUP  "&A1 i gnment" 

{ 

MENUITEM  "&Left",  IDM_LEFT, 

MENUITEM  "&Right\  IDM.RIGHT 

MENUITEM  "&Centered" ,  I DM_C ENTER 

MENUITEM  "&Justi fied",  IDM.JUST 

} 


CHECKED 


JUSTIFY.  ASC 

Call  me  Ishmael.  Some  years  ago  --  never  mind  how  long  precisely  - 
-  having  little  or  no  money  in  my  purse,  and  nothing  particular  to 
interest  me  on  shore,  I  thought  I  would  sail  about  a  little  and  see 
the  watery  part  of  the  world.  It  is  a  way  I  have  of  driving  off  the 
spleen,  and  regulating  the  circulation.  Whenever  I  find  myself 
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growing  grim  about  the  mouth;  whenever  it  is  a  damp,  drizzly  November 
in  my  soul;  whenever  I  find  myself  involuntarily  pausing  before  coffin 
warehouses,  and  bringing  up  the  rear  of  every  funeral  I  meet;  and 
especially  whenever  my  hypos  get  such  an  upper  hand  of  me,  that  it 
requires  a  strong  moral  principle  to  prevent  me  from  deliberately 
stepping  into  the  street,  and  methodically  knocking  people's  hats 
off  --  then,  I  account  it  high  time  to  get  to  sea  as  soon  as  I  can. 
This  is  my  substitute  for  pistol  and  ball.  With  a  philosophical 
flourish  Cato  throws  himself  upon  his  sword;  I  quietly  take  to  the 
ship.  There  is  nothing  surprising  in  this.  If  they  but  knew  it, 
almost  all  men  in  their  degree,  some  time  or  other,  cherish  very 
nearly  the  same  feelings  towards  the  ocean  with  me. 


JUSTIFY.H 

/* . 

JUSTIFY.H  header  file 

-*/ 

♦define  IDM.F0NT  10 

♦define  IDM_LEFT  20 

♦define  I DM_RI GHT  21 

♦define  IDM_CENTER  22 

♦define  IDM.JUST  23 


JUSTIFY.DEF 


JUSTIFY. DEF  module  definition  file 


NAME  JUSTIFY 

DESCRIPTION  'Demonstration  of  Justified  Text  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 
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Figure  14-12.  A  typical  JUSTIFY  display. 

Unlike  the  FONTLIST  program,  JUSTIFY  doesn’t  bother  with  enumerating  the  fonts 
itself  but  lets  the  ChooseFont  function  do  it.  ChooseFont  is  part  of  the  common  dialog  box 
library  and  displays  a  font  selection  dialog  box  similar  to  those  in  programs  included  with 
Windows  3.1,  such  as  WRITE.  This  function  uses  a  structure  of  type  CHOOSEFONT. 

The  CHOOSEFONT  structure  contains  a  pointer  to  a  LOGFONT  structure.  On  return 
from  the  ChooseFont  function,  the  fields  of  the  LOGFONT  structure  will  be  set  up  in 
preparation  for  calling  CreateFontlndirect.  However,  the  width  field  of  this  LOGFONT 
structure  will  be  in  units  of  pixels,  so  be  sure  that  the  MM_TEXT  mapping  mode  is  set 
when  you  select  the  font  into  a  device  context. 

JUSTIFY  displays  a  ruler  (in  logical  inches,  of  course)  across  the  top  and  down  the  left 
side  of  the  client  area.  The  DrawRuler  function  draws  the  ruler.  A  rectangle  structure 
defines  the  area  in  which  the  text  must  be  justified. 

The  text  is  a  user-defined  resource.  It  is  in  a  one-line-per-paragraph  format  and  is 
NULL-terminated.  The  bulk  of  the  work  involved  with  formatting  this  text  is  in  the  Justify 
function.  JUSTIFY  starts  searching  for  blanks  at  the  beginning  of  the  text  and  uses 
GetTextExtent  to  measure  each  line.  When  the  length  of  the  line  exceeds  the  width  of  the 
display  area,  JUSTIFY  returns  to  the  previous  space  and  uses  the  line  up  to  that  point. 
Depending  on  the  Alignment  choice,  the  line  is  left  aligned,  right  aligned,  centered,  or 
justified. 
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JUSTIFY  isn’t  perfect.  In  particular,  the  justification  logic  falls  apart  when  there  are 
fewer  than  two  words  in  each  line.  Even  if  we  solve  this  problem  (which  isn’t  a  particularly 
difficult  one),  the  program  still  won’t  work  properly  when  a  single  word  is  too  long  to  fit 
within  the  left  and  right  margins.  Of  course,  matters  can  become  even  more  complex  when 
you  start  working  with  programs  that  can  use  multiple  fonts  on  the  same  line  (as  Windows 
WRITE  can).  But  nobody  ever  claimed  this  stuff  was  easy.  It’s  just  easier  than  if  you  were 
doing  all  the  work  yourself. 


POPPAD  WITH  FONTS 

While  generalized  font  use  may  be  difficult,  adding  font  selection  to  POPPAD  is  not  tough 
at  all.  To  create  POPPAD4,  you  need  the  various  POPPAD  files  from  Chapter  10,  plus  the 
two  files  shown  in  Figure  14-13- 


POPPAD4.MAK 

# . . . 

#  P0PPAD4.MAK  make  file 

# 

poppad4.exe  :  poppad.obj  popfile.obj  popfind.obj  \ 

popfont.obj  popprntO.obj  poppad.res  poppad.def 
$(WINLINK)  poppad  popfile  popfind  popfont  popprnt0,  poppad4,  \ 
NUL,  $ (WI NLIB) ,  poppad 
rc  -t  poppad.res  poppad4.exe 

poppad.obj  :  poppad. c  poppad. h 
$ ( WI NCC )  poppad. c 

popfile.obj  :  popfile.c 
$ ( WI NCC )  popfile.c 

popfind.obj  :  popfind.c 
$ ( WI NCC )  popfind.c 

popfont.obj  :  popfont. c 
$ ( WI NCC )  popfont. c 

popprnt0.obj  :  popprnt0.c 
$ ( WI NCC )  popprnt0.c 

poppad.res  :  poppad. rc  poppad. h  poppad. ico 
$ ( WI NRC )  poppad. rc 


Figure  14-13.  The  new  POPPAD4 files. 
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POPFONT.C 

/* . . 

POPFONT.C  --  Popup  Editor  Font  Functions 
(c)  Charles  Petzold,  1992 
. - - - - */ 


#include  <windows.h> 

#include  <commdlg.h> 

static  LOGFONT  logfont  ; 
static  HFONT  hFont  ; 

BOOL  PopFontChooseFont  (HWND  hwnd) 
{ 


CH00SEF0NT  cf  ; 

cf .IStructSize 

_ 

sizeof  (CHOOSEFONT)  ; 

cf .hwndOwner 

= 

hwnd  ; 

cf.hDC 

= 

NULL  ; 

cf .lpLogFont 

= 

&logfont  ; 

cf .iPointSize 

= 

0  ; 

cf  .Flags 

= 

C F_I N ITTOLOGFONTSTRUCT  I  CF_SCREEN FONTS 

!  CF_E FFECTS  ; 

cf .rgbColors 

= 

0L  ; 

cf .lCustData  g 

= 

0L  ; 

cf.lpfnHook 

= 

NULL  ; 

cf .lpTemplateName 

= 

NULL  ; 

cf .hlnstance 

= 

NULL  ; 

cf .IpszStyle 

= 

NULL  ; 

cf .nFontType 

= 

0  ; 

//  returned  from  ChooseFont 

cf .nSizeMin 

= 

0  ; 

cf .nSizeMax 

= 

0  ; 

return  ChooseFont 

(&cf)  ; 

} 

void  PopFontlnitial ize  (HWND  hwndEdit) 

{ 

GetObject  (GetStockObject  (SYSTEM_FONT) ,  sizeof  (LOGFONT), 

(LPSTR)  &logfont)  ; 

hFont  =  CreateFontlndi rect  ( &1 ogf ont )  ; 

SendMessage  (hwndEdit,  WM_SETFONT,  hFont,  0L)  ; 

} 

void  PopFontSetFont  (HWND  hwndEdit) 

{ 

HFONT  hFontNew  ; 
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hFontNew  =  CreateFontlndirect  (&1 ogfont )  ; 
SendMessage  (hwndEdit,  WM_SETFONT,  hFontNew,  0L)  ; 
DeleteObject  (hFont)  ; 
hFont  =  hFontNew  ; 

} 

void  PopFontDeinitialize  (void) 

{ 

DeleteObject  (hFont)  ; 

} 


During  the  WM_CREATE  message,  POPPAD  calls  PopFontlnitialize  in  POPFONT.C. 
This  function  obtains  a  LOGFONT  structure  based  on  the  system  font,  creates  a  font  from 
it,  and  sends  a  WM_SETFONT  message  to  the  edit  control  to  set  a  new  font.  (Although  the 
default  edit  control  font  is  the  system  font,  the  PopFontlnitialize  function  creates  a  new 
font  for  the  edit  control  because  eventually  the  font  will  be  deleted,  and  it  wouldn’t  be  wise 
to  delete  the  stock  system  font.) 

When  POPPAD  receives  a  WM-COMMAND  message  for  the  program’s  font  option,  it 
calls  PopFontChooseFont .  This  function  initializes  a  CHOOSEFONT  structure  and  then 
calls  ChooseFont  to  display  the  font  selection  dialog  box.  If  the  user  presses  the  OK  button, 
ChooseFont will  return  TRUE.  POPPAD  then  calls  PopFontSetFonti o  set  the  new  font  in  the 
edit  control.  The  old  font  is  deleted. 

Finally,  during  the  WM_DESTROY  message,  POPPAD  calls  PopFontDeinitialize  to 
delete  the  last  font  that  PopFontSetFont  created. 
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Using  the 
Printer 


The  concept  of  device  independence  may  have  seemed  all  well  and  good  in  the  past  four 
chapters,  when  we  were  using  the  video  display  for  text  and  graphics,  but  how  well  does 
the  concept  hold  up  for  printers  and  plotters?  In  general,  the  news  is  good.  Under  Windows, 
printers  and  plotters  have  a  device-independent  graphics  interface.  You  can  forget  about 
printer  control  sequences  and  communications  protocols  when  programming  for  the 
printer.  Retail  Windows  programs  conspicuously  lack  the  disks  of  specialized  printer 
drivers  that  characterize  word-processing  software  and  graphics  programs  for  MS-DOS. 
When  a  retail  Windows  program  includes  printer  drivers,  they  are  usually  enhanced  ver¬ 
sions  of  existing  printer  drivers. 

From  a  Windows  program,  you  can  print  text  and  graphics  on  paper  using  the  same 
GDI  functions  that  we’ve  been  using  for  the  video  display.  Many  of  the  issues  of  device  in¬ 
dependence  that  we’ve  explored  in  the  past  four  chapters — mostly  related  to  the  size  and 
resolution  of  the  display  surface  and  its  color  capabilities — can  be  approached  and 
resolved  in  the  same  way.  Yet  a  printer  or  plotter  is  not  simply  a  display  that  uses  paper 
rather  than  a  cathode-ray  tube.  There  are  some  very  significant  differences.  For  example, 
we  have  never  had  to  consider  the  problem  of  a  video  display  not  being  connected  to  the 
display  adapter  or  the  problem  of  the  display  “running  out  of  screen,”  but  it  is  common  for 
a  printer  to  be  off  line  or  to  run  out  of  paper. 

Nor  have  we  worried  about  the  video  display  adapter  being  incapable  of  performing 
certain  graphics  operations.  Either  the  display  adapter  can  handle  graphics  or  it  can’t.  And 
if  it  can’t,  then  it  can’t  be  used  with  Windows  at  all.  But  some  printers  can’t  print  graphics 
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(although  they  can  still  be  used  with  Windows),  and  plotters  can  do  vector  graphics  but 
have  a  real  problem  with  bit-block  transfers. 

Here  are  some  other  issues  to  consider: 

■  Printers  are  slower  than  video  displays.  Although  we  have  on  occasion 
tried  to  tune  our  programs  for  best  performance,  we  haven’t  worried 
about  the  time  required  for  the  video  display  to  be  refreshed.  But  nobody 
wants  to  wait  for  a  printer  to  finish  printing  before  getting  back  to  work. 

■  Programs  reuse  the  surface  of  the  video  display  as  they  overwrite 
previous  display  output  with  new  output.  This  can’t  be  done  on  a  printer. 

Instead,  a  printer  must  eject  a  completed  page  and  go  on  to  the  next  page. 

■  On  the  video  display,  different  applications  are  windowed.  On  a  printer, 
output  from  different  applications  must  be  separated  into  distinct  docu¬ 
ments  or  print  jobs. 

To  add  printer  support  to  the  rest  of  GDI,  Windows  includes  only  one  new  function, 
called  Escape.  Well,  it’s  actually  more  than  one.  Escape  has  many  subfunctions  that  are 
indicated  by  one  of  the  Escape  parameters.  For  example,  the  three  most  common  Escape 
subfunctions  are  STARTDOC  and  ENDDOC  (which  begin  and  end  a  printing  job)  and 
NEWFRAME  (which  ends  one  page  and  goes  on  to  the  next). 

With  Windows  3.1,  it  is  not  necessary  to  use  the  Escape  function  for  most  common 
purposes.  Windows  3.1  includes  some  new  functions  (for  example,  StartDoc,  EndDoc, 
StartPage,  and  EndPage)  that  you  can  use  instead. 


PRINTING,  SPOOLING,  AND  ESCAPE 

When  you  use  a  printer  in  Windows,  you’re  actually  initiating  a  complex  interaction 
involving  the  GDI  library  module,  the  printer  device  driver  library  module  (which  has  a 
.DRV  extension),  and  the  Windows  Print  Manager  program  (PRINTMAN.EXE),  as  well  as 
some  other  modules  that  get  into  the  act.  Before  we  start  programming  for  the  printer, 
let’s  examine  how  this  process  works. 

When  an  application  program  wants  to  begin  using  a  printer,  it  first  obtains  a  handle 
to  the  printer  device  context  using  CreateDC.  This  causes  the  printer  device  driver  library 
module  to  be  loaded  into  memory  (if  it’s  not  present  already)  and  to  initialize  itself.  The 
program  then  calls  the  Escape  subfunction  named  STARTDOC,  which  signals  the  begin¬ 
ning  of  a  new  document.  The  Escape  function  is  handled  by  the  GDI  module.  The  GDI 
module  calls  the  Control  function  (which  is  equivalent  to  Escape )  in  the  printer  device 
driver.  The  device  driver  performs  some  initialization  and  calls  Openjob ,  which  is  in  the 
GDI  module.  The  GDI  module  then  loads  the  Windows  Print  Manager  program  into 
memory. 
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Following  the  STARTDOC  Escape  call,  the  program  can  make  the  appropriate  GDI 
calls  for  the  first  page  of  the  document.  For  example,  if  the  program  wants  to  draw  an 
ellipse  on  the  page,  it  calls  Ellipse ,  just  as  it  does  when  drawing  an  ellipse  on  the  screen. 
The  GDI  module  generally  stores  all  these  GDI  calls  in  a  disk -based  metafile,  which  is 
located  in  the  subdirectory  indicated  by  the  TEMP  variable  in  the  MS-DOS  environment.  (If 
no  TEMP  variable  exists,  Windows  uses  the  root  directory  of  the  first  fixed  disk  on  the 
system.)  The  file  begins  with  the  characters  ~MF  and  has  a  .TMP  extension.  However,  as  I’ll 
discuss  shortly,  it’s  possible  for  the  printer  driver  to  skip  this  step. 

When  the  application  program  is  finished  with  the  GDI  calls  that  define  the  first 
page,  the  program  calls  the  NEWFRAME  subfunction  of  Escape.  Now  the  real  work  begins. 
The  printer  driver  must  translate  the  various  drawing  commands  stored  in  the  metafile  into 
output  for  the  printer.  The  printer  output  required  to  define  a  page  of  graphics  can  be  very 
large,  particularly  if  the  printer  has  no  high-level  page-composition  language.  For  example, 
a  300-dots-per-inch  laser  printer  using  SV^-by-ll-inch  paper  might  require  more  than  a 
megabyte  of  data  to  define  one  page  of  graphics. 

For  this  reason,  printer  drivers  often  implement  a  technique  called  “banding,”  which 
divides  the  page  into  rectangles  called  bands.  (We’ll  examine  banding  later  in  this  chapter.) 
The  GDI  module  obtains  the  dimensions  of  each  band  from  the  printer  driver.  It  then  sets  a 
clipping  region  equal  to  this  band  and  calls  the  printer  device  driver  Output  function  for 
each  of  the  drawing  functions  contained  in  the  metafile.  This  process  is  called  “playing  the 
metafile  into  the  device  driver.”  The  GDI  module  must  play  the  entire  metafile  into  the  de¬ 
vice  driver  for  each  band  that  the  device  driver  defines  on  the  page.  After  the  process  is 
completed,  the  metafile  can  be  deleted. 

For  each  band,  the  device  driver  translates  these  drawing  functions  into  the  output 
necessary  to  realize  them  on  the  printer.  The  format  of  this  output  will  be  specific  to  the 
printer.  For  dot-matrix  printers,  it  will  be  a  collection  of  control  sequences,  including 
graphics  sequences.  (For  some  assistance  with  constructing  this  output,  the  printer  driver 
can  call  various  “helper”  routines  also  located  in  the  GDI  module.)  For  laser  printers  with  a 
high-level  page-composition  language  (such  as  PostScript),  the  printer  output  will  be  in 
that  language. 

The  printer  driver  uses  the  WriteSpool  function  to  pass  the  printer  output  for  each 
band  to  the  GDI  module,  which  then  stores  this  printer  output  in  a  temporary  file  also  lo¬ 
cated  in  the  TEMP  subdirectory.  This  file  begins  with  the  characters  ~SPL  and  has  a  .TMP 
extension.  When  the  entire  page  is  finished,  the  GDI  module  uses  the  SendMessage  func¬ 
tion  to  send  a  message  to  the  Print  Manager  indicating  that  a  new  print  job  is  ready.  The 
application  program  then  goes  on  to  the  next  page.  When  the  application  is  finished  with 
all  the  pages  it  must  print,  it  makes  the  ENDDOC  Escape  call  to  signal  that  the  print  job  is 
completed.  Figure  13-1  on  the  following  page  shows  the  interaction  of  the  program,  the 
GDI  module,  and  the  printer  driver. 
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The  Windows  Print  Manager  program  is  a  print  spooler  that  relieves  application  pro¬ 
grams  of  some  of  the  work  involved  with  printing.  The  GDI  module  loads  the  Print  Man¬ 
ager  (if  it  is  not  already  loaded)  automatically  when  a  program  begins  printing.  The  GDI 
module  then  creates  the  files  that  contain  printer  output.  The  Print  Manager’s  job  is  to  send 
these  files  out  to  the  printer.  It  is  notified  of  a  new  print  job  by  a  message  from  the  GDI 


SendMessage  call 
->-to  Print  Manager  to 
notify  of  new  print  job 


Figure  15-1 .  The  interaction  of  the  application  program,  the  GDI  module, 
and  the  printer  driver. 

module.  It  then  begins  reading  the  file  and  transferring  it  directly  to  the  printer.  To  transfer 
the  files,  the  Print  Manager  uses  various  communications  functions  ( OpenComm ,  Write - 
Comm ,  and  so  forth  included  in  the  USER  module)  for  the  parallel  or  serial  port  that  the 
printer  is  connected  to.  During  the  time  that  the  Print  Manager  is  writing  the  printer  output 
to  the  output  port,  other  Windows  programs  can  function  normally.  When  the  Print  Man¬ 
ager  is  done  sending  a  file  to  a  printer,  it  can  delete  the  temporary  file  holding  the  output. 
This  process  is  shown  in  Figure  15-2. 

Most  of  this  process  is  transparent  to  the  application  program.  From  the  perspective 
of  the  program,  “printing”  occurs  only  during  the  time  required  for  the  GDI  module  to  save 
all  the  printer  output  in  disk  files.  After  that,  the  program  is  freed  up  to  do  other  things. 
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The  actual  printing  of  the  document  becomes  the  Print  Manager’s  responsibility  rather 
than  the  program’s.  A  user  can  direct  the  Print  Manager  to  pause  print  jobs,  to  change  their 
priority,  or  to  cancel  print  jobs.  This  arrangement  allows  programs  to  “print”  faster  than 
would  be  possible  if  they  were  printing  in  real  time  and  had  to  wait  for  the  printer  to  finish 
one  page  before  proceeding  to  the  next. 


Figure  15-2.  The  operation  of  the  Print  Manager  program. 

Although  I’ve  described  how  printing  works  in  general,  there  are  some  variations  on 
this  theme.  One  is  that  the  Print  Manager  doesn’t  have  to  be  present  in  order  for  Windows 
programs  to  use  the  printer.  Normally,  the  [windows] section  ofWIN.INI  contains  this  line: 

Spool er=yes 

But  a  user  can  change  that  to: 

Spool er=no 

If  this  line  is  present,  the  Print  Manager  doesn’t  allow  itself  to  be  executed. 

Why  would  a  user  not  want  the  Print  Manager  to  be  loaded?  Well,  perhaps  the  user 
has  a  hardware  or  software  print  spooler  that  works  faster  than  the  Print  Manager.  Or 
perhaps  the  printer  is  on  a  network  that  has  its  own  spooler.  The  general  rule  is  that  one 
spooler  is  faster  than  two.  Removing  the  Windows  Print  Manager  would  speed  up  printing, 
because  the  printer  output  doesn’t  have  to  be  stored  on  disk.  It  can  go  right  out  to  the 
printer  and  be  intercepted  by  the  external  hardware  or  software  print  spooler. 

If  the  Print  Manager  can’t  be  loaded,  the  GDI  module  doesn’t  store  the  printer  output 
from  the  device  driver  in  a  file.  Instead,  GDI  itself  sends  the  output  directly  to  the  parallel 
or  serial  printer  port.  Unlike  the  printing  done  by  the  Print  Manager,  the  printing  done  by 
GDI  has  the  potential  of  holding  up  the  operation  of  application  programs  (particularly  the 
program  doing  the  printing)  until  the  printing  is  completed. 
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Here’s  another  variation  on  the  general  theme.  Normally,  the  GDI  module  stores  all 
the  functions  necessary  to  define  a  page  in  a  metafile  and  then  plays  this  metafile  into  the 
printer  driver  once  for  each  band  defined  by  the  driver.  If  the  printer  driver  doesn’t  require 
banding,  however,  the  metafile  isn’t  created;  GDI  simply  passes  the  drawing  functions  di¬ 
rectly  to  the  driver.  In  a  further  variation,  it  is  also  possible  for  an  application  to  assume 
responsibility  for  dividing  printer  output  into  bands.  This  makes  the  printing  code  in  the 
application  program  more  complex,  but  it  relieves  the  GDI  module  of  creating  the 
metafile.  Once  again,  GDI  simply  passes  the  functions  for  each  band  to  the  printer  driver. 

Now  perhaps  you’re  starting  to  see  how  printing  from  a  Windows  program  might  in¬ 
volve  a  bit  more  overhead  than  that  required  for  using  the  video  display.  Several  problems 
can  occur — particularly  if  the  GDI  module  runs  out  of  disk  space  while  creating  the 
metafile  or  the  printer  output  files.  You  can  either  get  very  involved  in  reporting  these 
problems  to  the  user  and  attempting  to  do  something  about  them,  or  you  can  remain 
relatively  aloof. 

We’ll  examine  several  different  approaches  to  printing  in  the  pages  that  follow.  But 
first  things  first — let’s  begin  by  obtaining  a  printer  device  context. 

THE  PRINTER  DEVICE  CONTEXT 

Just  as  you  must  obtain  a  handle  to  a  device  context  before  you  paint  on  the  video  display, 
you  must  obtain  a  printer  device  context  handle  before  printing.  Once  you  have  this  handle 
(and  have  made  the  Escape  calls  necessary  to  announce  your  intention  of  creating  a  new 
document),  you  can  use  this  printer  device  context  handle  the  same  way  you  use  the  video 
display  device  context  handle — as  the  first  parameter  to  the  various  GDI  calls  we’ve 
covered  in  the  last  four  chapters. 

In  Chapter  11,  you  learned  that  you  can  get  a  handle  to  a  device  context  for  the  entire 
video  display  by  calling: 

hdc  =  CreateDC  ("DISPLAY" ,  NULL,  NULL,  NULL)  ; 

You  obtain  a  printer  device  context  handle  using  this  same  function.  However,  for  a  printer 
device  context,  the  first  three  parameters  are  not  fixed.  The  general  syntax  of  CreateDC  is: 

hdc  =  CreateDC  (IpszDri verName,  lpszDeviceName,  1 pszOutputPort , 

1 plniti al i zati onData)  ; 

Although  IpInitializationData  is  generally  set  to  NULL,  the  first  three  parameters  must  be 
far  pointers  to  character  strings  that  tell  Windows  the  name  of  the  printer  driver,  the  name 
of  the  printer  device,  and  the  output  port  to  which  the  device  is  connected.  Before  you  can 
set  these  three  parameters,  you  must  do  a  little  fishing  in  the  WIN. INI  file. 
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Getting  the  CreateDC  Parameters 

Printers  are  listed  in  two  different  sections  of  the  WIN. INI  file,  reflecting  the  possibility 
that  a  system  can  have  more  than  one  printer  attached  to  it.  A  single  printer  is  listed  in  the 
[windows]  section  with  the  keyword  device.  The  string  that  follows  contains  the  device 
name,  driver  name,  and  output  port  required  in  the  CreateDC  call: 

[wi ndows] 

[other  lines] 

device=IBM  Graphics , IBMGRX, LPT1 : 

In  this  case,  the  device  name  is  IBM  Graphics,  the  driver  name  is  IBMGRX,  and  the  output 
port  is  LPT1.  The  printer  listed  in  this  section  ofWIN.INI  is  the  most  recent  printer  that  the 
user  has  selected  using  the  Windows  Control  Panel.  This  printer  is  chosen  from  the  dialog 
box  invoked  by  the  Printer  option.  It  can  be  considered  the  “current  printer”  or  the 
“default  printer.”  Most  small  Windows  programs  use  this  printer  for  printing. 

Here  is  one  way  to  write  a  function  to  obtain  this  string  from  WIN. INI,  parse  it  into 
the  three  components,  and  call  CreateDC  to  obtain  a  printer  device  context  handle: 

HDC  GetPri nterDC  0 

{ 

char  szPrinter  [80]  ; 

char  *$zDevice,  *szDriver,  *szOutput  ; 

GetProfileString  ("windows”,  "device",  szPrinter,  80)  ; 

4 

if  (NULL  !=  (szDevice  =  strtok  (szPrinter,  ","  ))  && 

NULL  !=  (szDriver  =  strtok  (NULL,  ",  "))  && 

NULL  !=  (szOutput  =  strtok  (NULL,  ",  "))) 

return  CreateDC  (szDriver,  szDevice,  szOutput,  NULL)  ; 

return  0  ; 

} 

GetProfileString  looks  in  the  [windows]  section  for  the  keyword  device  and  copies  up  to 
80  characters  following  the  equal  sign  into  szPrinter.  (The  third  parameter  to  GetProfile¬ 
String  is  a  default  string  if  Windows  can’t  find  the  [windows]  section  or  the  device  keyword 
in  WIN. INI.)  The  string  is  parsed  using  the  normal  C  strtok  function,  which  breaks  a  string 
into  tokens.  Note  that  I  use  only  a  comma  to  find  the  end  of  the  szDevice  string,  because 
the  device  name  can  include  embedded  blanks.  Both  a  comma  and  space  are  used  to  sepa¬ 
rate  the  driver  name  and  output  port  so  that  leading  or  trailing  blanks  are  stripped  from 
these  strings.  (Using  strtok  is  not  an  entirely  satisfactory  method  of  parsing  this  string,  be¬ 
cause  strtok  doesn’t  take  into  account  the  multibyte  character  codes  that  can  be  used  in 
versions  of  Windows  for  countries  in  the  Far  East.  If  this  is  of  concern,  you  can  write  your 
own  version  of  strtokth&t  uses  AnsiNextto  advance  through  the  string.) 

The  CreateDC  function  returns  0  if  the  printer  device  context  could  not  be  created. 
This  can  occur  if  the  string  in  WIN.INI  is  malformed,  if  Windows  can’t  find  the  printer 
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driver,  or  if  the  output  port  name  is  “none”  (which  means  the  printer  is  not  connected  to  an 
output  port).  You  can,  however,  obtain  an  information  context  for  a  printer  connected  to 
“none”  by  using  CreateIC  rather  than  CreateDC. 

The  [windows] section  ofWIN.INI  lists  only  one  printer,  but  multiple  printers  can  be 
listed  in  the  [devices]  section  of  WIN. INI.  A  printer  is  listed  in  this  section  when  a  user 
chooses  the  Add  New  Printer  option  from  the  Installation  menu  of  CONTROL.EXE.  The 
[devices] section  looks  something  like  this: 

[devi ces] 

IBM  Graph i cs=IBMGRX, LPT1 : 

Generic  /  Text  Only=TTY, output .prn 

HP  PI otter=HPPLOT,COMl : 

Postscri pt  Pri nter=PSCRIPT,C0M2: 

To  the  left  of  each  equal  sign  is  the  device  name;  to  the  right  is  first  the  driver  name  and 
then  the  output  port.  Getting  a  device  context  handle  using  the  printer  specified  in  the 
[windows]  section  ofWIN.INI  is  essentially  the  same  as  getting  a  device  context  handle 
using  one  of  the  printers  from  the  [devices] section,  except  that  the  latter  is  more  difficult 
because  you  have  more  than  one  choice. 

Some  larger  Windows  programs  include  a  File  menu  option  called  Change  Printer, 
which  invokes  a  dialog  box  that  lists  all  the  printers  from  the  [devices] section  and  the  port 
each  printer  is  connected  to.  This  option  allows  the  user  to  select  a  printer  other  than  the 
one  listed  in  the  [windows]  section  ofWIN.INI.  A  program  that  includes  this  option  must 
first  call  GetProfileString  with  a  NULL  second  parameter: 

static  char  szAllDevices  [4096]  ; 

[other program  lines] 

GetProfileString  ("devices”,  NULL,  szAllDevices, 

sizeof  szAllDevices)  ; 

On  return,  szAllDevices  contains  a  list  of  the  keywords  (the  device  names)  in  the  [devices] 
section.  Each  keyword  is  terminated  by  a  NULL  except  for  the  final  keyword,  which  is  ter¬ 
minated  by  two  NULLs.  For  the  example  list  shown  above,  szAllDevices  would  contain 
(using  C  notation): 

IBM  Graphi cs\0Generic  /  Text  On  1 y \0HP  PI otter\0Postscri pt  Printer\0\0 

You  can  then  present  these  names  to  the  user.  (WeTl  do  this  shortly  in  the  DEVCAPS2 
program.) 

Let’s  assume  that  a  user  selects  one  of  these  devices  and  that  you’ve  set  the  pointer 
szDevice  to  the  beginning  of  that  device  name  in  szAllDevices.  You  can  then  obtain  the  rest 
of  the  string  (the  driver  name  and  output  port)  by  calling  GetProfileString  again: 

GetProfileString  ("devices",  szDevice,  "",  szPrinter,  64)  ; 
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You  need  to  parse  the  szPrinter string  to  extract  the  driver  name  and  the  output  port  name: 

szDriver  =  strtok  (szPrinter,  ",  ")  ; 
szOutput  =  strtok  (NULL  ,  ",  ")  ; 

Now  you  have  the  szDevice ,  szDriver ;  and  szOutput  pointers  necessary  to  call  CreateDC 
or  CreatelC. 

The  valid  output  ports  on  a  particular  system  are  listed  in  the  [ports]  section  of 
WIN. INI.  You  don’t  need  to  access  this  section  of  WIN. INI  to  use  the  printer.  You  can 
assume  that  the  user  has  identified  a  particular  port  for  the  printer  using  the  Printer  option 
in  the  Control  Panel,  and  you  can  further  assume  that  the  user  has  properly  defined  the 
communications  parameters  for  serial  (COM)  ports  using  the  Ports  option. 

The  [ports]  section  often  looks  something  like  this: 

[ports] 

LPT1 := 

LPT  2 :  = 

LPT3 :  = 

C0M1 : =9600 , n , 8 , 1 
COM2:=1200,n,8,l 
output. prn= 

The  OUTPUT.PRN  file  (or  any  file  with  a  .PRN  extension)  can  be  listed  here  to  direct 
printer  output  to  a  file.  This  filename  can  appear  as  the  output  port  for  a  printer  in  the 
[windows] section  or  [devices] section  ofWIN.INI. 

The  Revised  DEVCAPS  Program 

The  original  DEVCAPS1  program  in  Chapter  11  displays  all  the  information  available  from 
the  GetDeviceCaps  function  for  the  video  display  and  the  current  printer.  The  new  version, 
shown  in  Figure  15-3,  displays  a  menu  of  all  the  printers  from  the  [devices]  section  of 
WIN. INI  and  lets  you  choose  one.  In  addition  to  the  DEVCAPS2  files  shown  here,  you’ll 
also  need  the  DEVCAPS.C  file  from  Chapter  11  (Figure  11-1). 

DEVCAPS2.MAK 

# 

#  DEVCAPS2.MAK  make  file 
#-- 

devcaps2.exe  :  devcaps2.obj  devcaps.obj  devcaps2.res  devcaps2.def 
$(WINLINK)  devcaps2  devcaps,  devcaps2,  NUL,  $( WINLIB) .  devcaps2 
rc  -t  devcaps2. res 

devcaps2.obj  :  devcaps2.c  devcaps2.h 
$ ( WI NCC )  devcaps2.c 

Figure  15-3.  The  DEVCAPS2 program.  (continued) 
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devcaps.obj  :  devcaps.c 
$ ( WI NCC )  devcaps.c 

devcaps2.res  :  devcaps2.rc  devcaps2.h 
$ ( WI NRC )  devcaps2.rc 


DEVCAPS2.C 

/* . — . — . . . 

DEVCAPS2.C  --  Displays  Device  Capability  Information  (Version  2) 

(c)  Charles  Petzold,  1992 

. . . --*/ 


//include  <windows.h> 

//include  <string.h> 

//include  ,,devcaps2.h" 

void  DoBasicInfo  (HDC,  HDC,  short,  short)  ;  //  in  DEVCAPS.C 

void  DoOtherlnfo  (HDC,  HDC,  short,  short)  ; 

void  DoBitCodedCaps  (HDC,  HDC,  short,  short,  short)  ; 

typedef  VOID  (FAR  PASCAL  * DEVMODE PROC )  (HWND,  HANDLE,  LPSTR,  LPSTR)  ; 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName[]  =  "DevCaps2"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. IpszMenuName 
wndclass. IpszClassName 


CS.HREDRAW  !  CS.VREDRAW; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL,  I DI_APPLI CATI ON )  ; 
LoadCursor  (NULL,  IDCJ\RR0W)  ; 
GetStockObject  (WHITE.BRUSH)  ; 
szAppName  ; 
szAppName  ; 


(continued) 
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RegisterClass  (&wndc1ass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  NULL, 

WS_OVERLAPPEDWINDOW, 

CWJJSEDEFAULT,  CWJJSEDEFAULT, 
CW.USEDEFAULT,  COSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  ( &msg )  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  DoEscSupport  (HDC  hdc,  HDC  hdclnfo,  short  cxChar,  short  cyChar) 
( 

static  struct 
{ 

char  *szEscCode  ; 
short  nEscCode  ; 

} 

esc  []  = 

{ 

"NEWFRAME",  NEWFRAME, 

"ABORTDOC",  ABORTDOC, 

"NEXTBAND",  NEXTBAND, 

"SETCOLORTABLE",  SETCOLORTABLE, 

"GETCOLORTABLE" .  GETCOLORTABLE , 

"FLUSHOUTPUT",  FLUSHOUTPUT, 

’’DRAFTMODE",  DRAFTMODE, 

’’QUERYESCSUPPORT",  QUERYESCSUPPORT, 

"SETABORTPROC" ,  SETABORTPROC , 

"STARTDOC",  STARTDOC, 

"ENDDOC",  ENDDOC, 

"GETPHYSPAGESIZE",  GETPHYSPAGES I ZE , 

"GETPRINTINGOFFSET",  GETPRI NTI NGOFFSET , 

"GETSCALINGFACTOR",  GETSCALINGFACTOR  }  ; 

static  char  *szYesNo  []  =  {  "Yes",  "No"  }  ; 

char  szBuffer  [32]  ; 

POINT  pt  ; 

short  n,  nReturn  ; 

TextOut  (hdc,  cxChar,  cyChar,  "Escape  Support",  14)  ; 


(continued) 


739 


SECTION  IV:  THE  GRAPHICS  DEVICE  INTERFACE 


for  (n  =  0  ;  n  <  sizeof  esc  /  sizeof  esc  [0]  ;  n++) 

{ 

nReturn  =  Escape  (hdclnfo,  QUERYESCSUPPORT,  1. 

( LPSTR)  &  esc[n]. nEscCode,  NULL)  ; 
TextOut  (hdc,  6  *  cxChar,  (n  +  3)  *  cyChar,  szBuffer, 

wsprintf  (szBuffer,  "%-24s  %3s",  (LPSTR)  esc[n] .szEscCode, 
(LPSTR)  szYesNo  [nReturn  >  0  ?  0  :  1]))  ; 

if  (nReturn  >  0  &&  esc[n].nEscCode  >=  6ETPHYSPAGESIZE 
&&  esc[n] .nEscCode  <=  GETSCALINGFACTOR) 

{ 

Escape  (hdclnfo,  esc[n] .nEscCode,  0,  NULL,  (LPSTR)  &pt)  ; 
TextOut  (hdc.  36  *  cxChar,  (n  +  3)  *  cyChar,  szBuffer, 
wsprintf  (szBuffer,  "(%u.%u)",  pt.x,  pt.y))  ; 

} 

) 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  char  szAllDevices  [4096],  szDevice  [32],  szDriver  [16], 
szDriverFile  [16],  szWindowText  [64]  ; 
static  HANDLE  hLibrary  ; 

static  short  n,  cxChar,  cyChar,  nCurrentDevice  =  IDM.SCREEN, 

nCurrentlnfo  =  IDM.BASIC  ; 

char  *szOutput,  *szPtr  ; 

DEVMODEPROC  lpfnDM  ; 

HDC  hdc,  hdclnfo  ; 

HMENU  hMenu  ; 

PAINTSTRUCT  ps  ; 

TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

SelectObject  (hdc.  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

GetTextMetrics  (hdc,  &tm)  ; 

cxChar  =  tm. tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm. tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 

IParam  =  NULL  ; 

//  fall  through 

case  WM_WI N INICHANGE  : 

if  (IParam  !=  NULL  &&  Istrcmp  ((LPSTR)  IParam,  "devices")  !=  0) 
return  0  ; 
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hMenu  =  GetSubMenu  (GetMenu  (hwnd),  0)  ; 

while  (GetMenuItemCount  (hMenu)  >  1) 

DeleteMenu  (hMenu,  1,  MF.BYPOSITION)  ; 

GetProf i  1  eStri ng  ("devices",  NULL,  "",  szAUDevices, 
sizeof  szAUDevices)  ; 

n  =  IDM.SCREEN  +  1  ; 
szPtr  =  szAUDevices  ; 
while  (*szPtr) 

{ 

AppendMenu  (hMenu,  n  %  16  ?  0  :  MF_MENUBARBREAK,  n,  szPtr)  ; 
n++  ; 

szPtr  +=  strlen  (szPtr)  +  1  ; 

} 

AppendMenu  (hMenu,  M  F_S  E  PA  RAT  0  R ,  0,  NULL)  ; 

AppendMenu  (hMenu,  0,  IDM_DEVMODE,  "Device  Mode")  ; 

wParam  =  IDM_SCREEN  ; 

//  fall  through 

case  WM.COMMAND  : 

hMenu  =  GetMenu  (hwnd)  ; 

if  (wParam  <  IDM.DEVMODE)  //  IDM.SCREEN  &  Printers 

{ 

CheckMenuItem  (hMenu,  nCurrentDevice,  MFJJNCHECKED)  ; 
nCurrentDevice  =  wParam  ; 

CheckMenuItem  (hMenu,  nCurrentDevice,  MF_CHECKED)  ; 

} 

else  if  (wParam  ==  IDM.DEVMODE) 

{ 

GetMenuString  (hMenu,  nCurrentDevice,  szDevice, 
sizeof  szDevice,  MF_BYCOMMAND)  ; 

GetProf i leString  ("devices",  szDevice,  "", 

szDriver,  sizeof  szDriver)  ; 

szOutput  =  strtok  (szDriver,  ",  ")  ; 

strcat  (strcpy  (szDri verFile,  szDriver),  ".DRV")  ; 

if  (-hLibrary  >=  32) 

FreeLibrary  (hLibrary)  ; 

hLibrary  =  LoadLibrary  (szDri verFile)  ; 
if  (hLibrary  >=  32) 

{ 

lpfnDM  =  (DEVMODEPROC) 

GetProcAddress  (hLibrary,  "DEVICEMODE")  ; 
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lpfnDM  (hwnd,  hLibrary,  szDevice,  szOutput)  ; 

} 

} 

else  //  info  menu  items 

{ 

CheckMenuItem  (hMenu,  nCurrentlnfo,  MF_UNCHECKED)  ; 
nCurrentlnfo  =  wParam  ; 

CheckMenuItem  (hMenu,  nCurrentlnfo,  MF_CHECKED)  ; 

} 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

case  WM_I N ITMENUPOPUP  : 
if  (IParam  ==  0) 

EnableMenuItem  (GetMenu  (hwnd),  IDM_DEVMODE, 
nCurrentDevice  ==  I DM_SCREEN  ? 

MF.GRAYED  :  MF_ENABLED)  ; 

return  0  ; 
case  WM_PA I NT  : 

strcpy  (szWindowText,  "Device  Capabilities:  ")  ; 

if  (nCurrentDevice  ==  IDM_SCREEN) 

{ 

strcpy  (szDriver,  "DISPLAY")  ; 

strcat  (szWindowText,  szDriver)  ; 

hdclnfo  =  CreateIC  (szDriver,  NULL,  NULL,  NULL)  ; 

} 

else 

{ 

hMenu  =  GetMenu  (hwnd)  ; 

GetMenuString  (hMenu,  nCurrentDevice,  szDevice, 
sizeof  szDevice,  MF_BYCOMMAND)  ; 

GetProf i 1 eStri ng  ("devices",  szDevice,  "",  szDriver,  10)  ; 
szOutput  =  strtok  (szDriver,  ",  ")  ; 
strcat  (szWindowText,  szDevice)  ; 

hdclnfo  =  CreateIC  (szDriver,  szDevice,  szOutput,  NULL)  ; 

} 

SetWindowText  (hwnd,  szWindowText)  ; 
hdc  =  BeginPaint  (hwnd,  &ps)  ; 

SelectObject  (hdc,  GetStockObject  (SYSTEM_FIXED_FONT) )  ; 

if  (hdclnfo) 

{ 

switch  (nCurrentlnfo) 

{ 

case  IDM.BASIC  : 
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DoBasi clnfo  (hdc,  hdclnfo,  cxChar,  cyChar)  ; 
break  ; 

case  IDM.OTHER  : 

DoOtherlnfo  (hdc,  hdclnfo,  cxChar,  cyChar)  ; 
break  ; 

case  IDM_CURVE  : 
case  I DM__LI N E  : 
case  IDM_P0LY  : 
case  IDM.TEXT  : 

DoBitCodedCaps  (hdc,  hdclnfo,  cxChar,  cyChar, 
nCurrentlnfo  -  IDM.CURVE)  ; 
break  ; 

case  IDM.ESC  : 

DoEscSupport  (hdc,  hdclnfo,  cxChar,  cyChar)  ; 
break  ; 

} 

DeleteDC  (hdclnfo)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

if  (hLibrary  >=  32) 

FreeLibrary  (hLibrary)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


DEVCAPS2.RC 

/* . - 

DEVCAPS2.RC  resource  script 
. -*/ 

//include  "devcaps2.h" 

DevCaps2  MENU 
{ 

POPUP  "&Device" 

{ 

MENUITEM  "&ScreenM ,  I DM__SCREEN ,  CHECKED 
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} 

POPUP  '^Capabilities" 

{ 

MENUITEM  "&Basic  Information", 
MENUITEM  "&0ther  Information", 
MENUITEM  "&Curve  Capabilities", 
MENUITEM  "&Line  Capabilities", 
MENUITEM  "&Polygonal  Capabilities". 
MENUITEM  "&Text  Capabilities", 
MENUITEM  SEPARATOR 
MENUITEM  "&Escape  Support", 

} 

} 


IDM.BASIC,  CHECKED 

IDM.OTHER 

IDM.CURVE 

IDM.LINE 

IDM.POLY 

IDM.TEXT 

IDM.ESC 


DEVCAPS2.H 


/* . 

DEVCAPS2.H  header  file 

. */ 


♦define  IDM_SCREEN  1 

♦define  IDM.DEVMODE  0x100 

♦define  IDM.BASIC  0x101 
♦define  IDM.0THER  0x102 
♦define  IDM.CURVE  0x103 
♦define  IDM.LINE  0x104 
♦define  IDM.P0LY  0x105 
♦define  IDM.TEXT  0x106 
♦define  IDM.ESC  0x107 


DEVCAPS2.DEF 


DEVCAPS2 . DEF  module  definition  file 


NAME  DEVCAPS2 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 
STACKS I ZE 


'Displays  Device  Capability  Info  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 
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Because  DEVCAPS2  obtains  only  an  information  context  for  the  printer,  you  can  select 
printers  from  DEVCAPS2’s  menu,  even  though  they  may  have  an  output  port  of  “none.”  If 
you  want  to  compare  the  capabilities  of  different  printers,  you  can  first  use  the  Control 
Panel  to  add  various  printer  drivers  to  WIN. INI. 

DEVCAPS2  has  an  additional  option  on  the  Capabilities  menu  called  Escape  Support, 
which  lets  you  see  which  of  the  more  common  Escape  subfunctions  are  supported  by  the 
device  driver.  This  information  will  become  more  meaningful  a  little  later  in  this  chapter, 
when  we  discuss  the  Escape  function  and  its  subfunctions. 

The  DeviceMode  Call 

The  Device  menu  of  the  DEVCAPS2  program  includes  an  option  called  Device  Mode.  To 
use  it,  first  select  a  printer  from  the  Device  menu,  and  then  select  Device  Mode:  Up  pops  a 
dialog  box.  Where  did  the  dialog  box  come  from?  It  is  invoked  by  the  printer  driver,  and — 
at  the  very  least — it  requests  that  you  make  a  choice  of  paper  size.  Most  printer  drivers  also 
give  you  a  choice  of  “portrait”  or  “landscape”  mode.  In  portrait  mode  (often  the  default), 
the  short  side  of  the  paper  is  the  top;  in  landscape  mode,  the  long  side  is  the  top.  If  you 
change  this  mode,  the  change  is  reflected  in  the  information  the  DEVCAPS2  program  ob¬ 
tains  from  the  GetDeviceCaps  function:  The  horizontal  size  and  resolution  are  switched 
with  the  vertical  size  and  resolution.  Device  Mode  dialog  boxes  for  color  plotters  can  be 
quite  extensive,  requesting  the  colors  of  the  pens  installed  in  the  plotter  and  the  type  of 
paper  (or  transparencies)  being  used. 

All  printer  drivers  contain  an  exported  function  called  DeviceMode  that  invokes  this 
dialog  box  and  saves  the  information  that  the  user  enters.  Some  printer  drivers  store  this  in¬ 
formation  in  their  own  section  of  the  WIN. INI  file,  and  some  don’t.  Those  that  store  the 
information  have  access  to  it  during  the  next  Windows  session. 

Windows  programs  that  allow  the  user  a  choice  of  printers  generally  call  the  Device- 
Mode  function  of  the  printer  driver  so  that  the  user  can  make  changes  in  preparation  for 
printing.  Calling  this  function  from  a  program  requires  a  technique  that  we’ll  learn  more 
about  in  Chapter  19-  Here’s  how  DEVCAPS2  does  it. 

The  program  first  obtains  the  name  of  the  printer  currently  selected  in  the  Device 
menu  and  saves  it  in  a  character  array  named  szDevice : 

GetMenuString  (hMenu,  nCurrentDevice,  szDevice, 
sizeof  szDevice,  MF_BYCOMMAND)  ; 

Then  it  obtains  the  driver  name  and  output  port  of  this  device  using  GetProfileString.  This 
information  is  stored  in  szDriver. 

GetProfileString  ("devices",  szDevice,  "", 

szDriver,  sizeof  szDriver)  ; 
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The  output  port  is  separated  from  the  szDriver string  using  strtok,  and  the  pointer  is  saved 
in  szOutput : 

szOutput  =  strtok  (szDriver,  ",  ")  ; 

The  szDriver  string  contains  the  name  of  the  driver,  which  is  the  driver’s  filename  without 
the  .DRV  extension.  This  statement  creates  the  full  name  of  the  driver  file  and  saves  it  in 
szDriverFile : 

strcat  (strcpy  (szDriverFile,  szDriver),  ".DRV'’)  ; 

This  driver  file  is  a  dynamic  link  library  module.  (Library  modules  are  the  subject  of  Chap¬ 
ter  19.)  We  can  obtain  a  handle  to  this  module  (which  is  actually  the  instance  handle  of  the 
module)  by  calling  LoadLibrary.  If  LoadLibrary  returns  a  value  greater  than  or  equal  to  32, 
the  function  was  successful.  Otherwise,  the  return  value  indicates  an  MS-DOS  error  code. 

The  library  can  be  freed  by  a  call  to  FreeLibrary.  If  no  other  program  is  using 
this  library,  then  it  can  be  deleted  from  memory.  DEVCAPS2  holds  the  library  handle 
(or  whatever  was  returned  from  LoadLibrary)  in  a  static  variable,  so  before  trying  to  load  a 
new  library,  it  first  frees  the  old  one  if  the  handle  was  valid: 

if  (hLibrary  >=  32) 

FreeLibrary  (hLibrary)  ; 

hLibrary  =  LoadLibrary  (szDriverFile)  ; 

Before  proceeding,  the  program  checks  to  see  if  this  new  handle  is  valid: 

if  (hLibrary  >=  32) 

It  then  calls  GetProcAddress  to  obtain  the  address  of  the  DeviceMode  function: 

lpfnDM  =  (DEVMODEPROC)  GetProcAddress  (hLibrary,  "DEVICEMODE”)  ; 

DEVMODEPROC  is  defined  in  a  typedefs tatement.  The  DeviceMode  function  can  be  called 
by  passing  it  the  window  handle,  library  module  handle,  device  name,  and  output  port: 

lpfnDM  (hwnd,  hLibrary,  szDevice,  szOutput)  ; 

This  invokes  the  dialog  box. 

The  currently  loaded  driver  file  is  freed  when  the  program  terminates: 

case  WM.DESTROY  : 

if  (hLibrary  >=  32) 

FreeLibrary  (hLibrary)  ; 

The  LoadLibrary  call  increments  the  library  module’s  “reference  count”  (a  number  Win¬ 
dows  maintains  to  indicate  the  number  of  programs  using  a  module),  and  the  FreeLibrary 
call  decrements  it.  The  library  can  be  freed  from  memory  when  the  reference  count  is  0. 
Calls  to  CreateDC  and  CreateIC  for  a  printer  driver  also  increment  the  reference  count, 
and  DeleteDC decrements  it. 


746 


Chapter  15:  Using  the  Printer 


Checking  for  BitBIt  Capability 

You  can  use  the  GetDeviceCaps  function  to  obtain  the  size  and  resolution  of  the  printable 
area  of  the  page.  (In  most  cases,  this  area  won’t  be  the  same  as  the  full  size  of  the  paper.) 
You  can  also  obtain  the  relative  pixel  width  and  height,  if  you  want  to  do  your  own  scaling. 

You  can  obtain  another  important  printer  characteristic  from  the  RC-BITBLT  bit  of 
the  value  returned  from  GetDeviceCaps  with  a  parameter  of  RASTERCAPS  (“raster  capa¬ 
bilities”).  This  bit  indicates  whether  the  device  is  capable  of  bit-block  transfers.  Most  dot¬ 
matrix  and  laser  printers  are  capable  of  bit-block  transfers,  but  most  plotters  are  not. 
Devices  that  can’t  handle  bit-block  transfers  do  not  support  the  following  GDI  functions: 
CreateCompatibleDC \  CreateCompatibleBitmap ,  PatBlt ,  BitBIt ,  StretchBlt ,  GrayString, 
Drawlcon ,  SetPixel,  GetPixel ,  FloodFill,  ExtFloodFill,  FillRgn ,  FrameRgn ,  InvertRgn, 
PaintRgn,  FillRect ,  FrameRect,  and  InvertRect.  This  is  the  single  most  important  distinction 
between  using  GDI  calls  on  a  video  display  and  using  them  on  a  printer. 

PRINTING  FUNDAMENTALS 

We’re  now  ready  to  print,  and  we’re  going  to  start  as  simply  as  possible.  In  fact,  our  first  two 
printing  programs  will  be  so  simple  that  they  won’t  work  unless  the  Print  Manager  pro¬ 
gram  is  loaded  when  printing  begins.  (The  Print  Manager  doesn’t  get  loaded  automatically 
if  a  user  specifies  Spooler=no  in  the  WIN. INI  file  or  if  Windows  can’t  find  the  PRINT- 
MAN. EXE  file.) 

The  Escape  Function 

The  Windows  GDI  module  includes  only  one  function — Escape — to  support  the  addi¬ 
tional  requirements  of  printers.  The  name  of  this  function  implies  that  it  is  ignored  by  the 
GDI  module  and  that  it  goes  straight  to  the  printer  driver.  In  some  cases,  this  is  true,  but 
often  GDI  also  does  some  work  during  Escape  calls. 

The  general  syntax  of  Escape  is: 

nResult  =  Escape  (hdcPrinter,  nEscapeCode,  nCount, 
lpsDataln,  IpsDataOut)  ; 

The  nEscapeCode  parameter  is  a  subfunction  code  that  is  specified  using  an  identifier 
defined  in  WINDOWS.H.  The  last  three  parameters  depend  on  the  subfunction.  Although 
the  last  two  parameters  are  declared  as  far  pointers  to  character  strings,  they  are  sometimes 
far  pointers  to  structures.  To  cast  the  pointers  into  far  pointers  to  strings,  use  (LPSTR). 

Not  all  Escape  subfunctions  are  implemented  in  all  device  drivers.  In  fact,  Escape  has 
been  designed  to  be  open-ended  so  that  manufacturers  of  display  devices  can  define  their 
own  Escape  subfunctions  to  access  certain  unique  facilities  of  the  devices.  The  following 
Escape  subfunctions  are  the  ones  I  discuss  in  this  chapter.  They  are  implemented  in  all 
printer  drivers: 
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nEscapeCode 

Description 

STARTDOC 

Starts  a  document 

ENDDOC 

Ends  a  document 

SETABORTPROC 

Sets  a  pointer  to  the 
“abort  procedure” 

NEWFRAME 

Ends  the  current  page 

NEXTBAND 

Gets  rectangle  coordi¬ 
nates  for  the  next  band 

nEscapeCode 

Description 

ABORTDOC 

Aborts  printing  of 

a  document 

GETPHYSPAGESIZE 

Gets  the  physical  size 

of  the  paper 

QUERYESCSUPPORT 

Finds  out  if  the  driver 

supports  an  Escape 

code 

DEVCAPS2  used  the  QUERYESCSUPPORT  subfunction  to  list  supported  Escape  functions. 
The  GETPHYSPAGESIZE  subfunction  returns  the  size  of  the  paper,  which  will  generally  be 
larger  than  the  printable  area  obtained  from  GetDe viceCaps.  We’ll  use  other  subfunctions 
in  programs  later  in  this  chapter.  Escape  always  returns  0  if  the  subfunction  is  not  imple¬ 
mented  and  a  negative  value  if  an  error  occurs.  A  positive  value  indicates  success. 

The  FORMFEED  Program 

Our  first  printing  program  does  nothing  but  cause  a  printer  formfeed  to  eject  the  page. 
The  FORMFEED  program,  shown  in  Figure  15-4,  demonstrates  the  absolute  minimum 
requirements  for  printing. 

FORMFEED.MAK 

# 

#  FORMFEED.MAK  make  file 

#  . 

formfeed.exe:  formfeed.obj  formfeed.def 

$(WINLINK)  formfeed,  formfeed,  NUL,  $(WINLIB),  formfeed 
rc  -t  formfeed.exe 

formfeed.obj:  formfeed.c 
$ ( WI NCC )  formfeed.c 


FORMFEED.C 

/* . 

FORMFEED.C  --  Advances  printer  to  next  page 
(c)  Charles  Petzold,  1992 
. - . . . */ 


Figure  15-4.  The  FORMFEED  program. 
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#include  <windows.h> 

#include  <string.h> 

HDC  GetPrinterDC  (void)  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szMsg  []  =  "FormFeed"  ; 

HDC  hdcPrint  ; 

hdcPrint  =  GetPrinterDC  ()  ; 

if  (hdcPrint  !=  NULL) 

{ 

if  (Escape  (hdcPrint,  STARTDOC,  sizeof  szMsg  -  1,  szMsg,  NULL)  >  0) 
if  (Escape  (hdcPrint,  NEWFRAME,  0,  NULL,  NULL)  >  0) 

Escape  (hdcPrint,  ENDDOC,  0,  NULL,  NULL)  ; 

DeleteDC  (hdcPrint)  ; 

} 

return  FALSE  ; 

} 

HDC  GetPrinterDC  (void) 

{ 

static  char  szPrinter  [80]  ; 

char  *szDevice,  *szDriver,  *szOutput  ; 

GetProf i 1 eStri ng  ("windows”,  "device",  ",,,",  szPrinter,  80)  ; 

if  (NULL  !=  (szDevice  =  strtok  (szPrinter,  ","  ))  && 

NULL  !=  (szDriver  =  strtok  (NULL,  ",  "))  && 

NULL  !=  (szOutput  =  strtok  (NULL,  ",  "))) 

return  CreateDC  (szDriver,  szDevice,  szOutput,  NULL)  ; 

return  0  ; 

} 


FORMFEED. DEF 


FORMFEED. DEF  module  definition  file 


NAME  FORMFEED 


(continued) 
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DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Printer  Form  Feed  Program  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


FORMFEED  includes  the  GetPrinterDC  function  shown  earlier.  Other  than  obtaining  the 
printer  device  context  (and  later  deleting  it),  the  program  makes  only  three  Escape  calls. 
The  first  uses  the  STARTDOC  subfunction  to  start  a  new  document.  It  tests  the  return  value 
from  Escape  and  proceeds  only  if  the  value  is  positive: 

if  (Escape  (hdcPrint,  STARTDOC,  sizeof  szMsg  -  1,  szMsg,  NULL)  >  0) 

The  fourth  parameter  is  a  far  pointer  to  the  string  that  the  Print  Manager  will  display  in  its 
client  area  to  identify  the  document  being  printed.  Generally,  this  string  includes  the  name 
of  the  application  doing  the  printing  and  the  file  being  printed.  In  this  case,  it’s  simply  the 
name  “FormFeed.”  The  third  parameter  is  the  length  of  this  string. 

If  STARTDOC  is  successful  (indicated  by  a  positive  return  value),  then  FORMFEED 
calls  the  NEWFRAME  Escape  subfunction,  which  advances  the  printer  to  a  new  page. 
Once  again,  the  return  value  is  tested: 

if  (Escape  (hdcPrint,  NEWFRAME,  0,  NULL,  NULL)  >  0) 

The  third,  fourth,  and  fifth  parameters  are  not  used  in  this  Escape  call. 

Finally,  if  everything  has  proceeded  without  error  to  this  point,  the  document  is 
ended: 

Escape  (hdcPrint,  ENDDOC,  0,  NULL,  NULL)  ; 

Again,  the  last  three  parameters  are  not  used.  Note  that  the  ENDDOC  Escape  function  is 
called  only  if  no  printing  errors  have  been  reported.  If  one  of  the  other  Escape  functions 
returns  an  error  code,  then  GDI  has  already  aborted  the  document.  If  the  printer  is  not  cur¬ 
rently  printing,  such  an  error  code  often  results  in  the  printer  being  reset. 

Simply  testing  the  return  values  from  the  Escape  calls  is  the  easiest  way  to  check  for 
errors.  However,  WINDOWS. H  includes  identifiers  for  the  error  codes,  which  you  can  use 
if  you  want  to  report  the  particular  error  to  the  user.  For  example,  the  NEWFRAME  Escape 
call  could  return  the  SP_OUTOFDISK  error  (-4),  indicating  insufficient  disk  space  for  GDI 
to  store  the  printer  output  necessary  to  trigger  the  printer  to  do  a  formfeed.  For  most  print¬ 
ers,  this  occurrence  is  extremely  unlikely.  For  your  own  amusement,  however,  you  might 
try  specifying  the  PostScript  printer  driver  as  your  current  printer,  with  the  output  port 
OUTPUT.PRN.  Run  FORMFEED  and  check  the  size  of  the  file.  (It  will  be  over  11  KB!) 

If  you’ve  ever  written  a  simple  formfeed  program  for  MS-DOS,  you  know  that  ASCII 
number  12  activates  a  formfeed  for  most  printers.  Why  not  simply  open  the  printer  port 
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using  the  C  library  function  open  and  then  output  an  ASCII  number  12  using  write ?  Well, 
nothing  prevents  you  from  doing  this.  You  first  have  to  determine  the  parallel  port  or  the 
serial  port  the  printer  is  attached  to — that’s  available  from  WIN. INI.  You  then  have  to  de¬ 
termine  if  another  program  (the  Print  Manager,  for  instance)  is  currently  using  the  printer. 
You  don’t  want  the  formfeed  to  be  output  in  the  middle  of  a  document,  do  you?  Finally,  you 
have  to  determine  if  ASCII  number  12  is  a  formfeed  character  for  the  connected  printer.  It’s 
not  universal,  you  know.  In  fact,  the  formfeed  command  in  PostScript  isn’t  a  12;  it’s  the  word 
showpage. 

In  short,  don’t  even  think  about  going  around  Windows;  stick  with  the  Windows 
functions  for  printing. 


PRINTING  GRAPHICS  AND  TEXT 

Printing  from  a  Windows  program  usually  involves  more  overhead  than  shown  in  the 
FORMFEED  program,  as  well  as  some  GDI  calls  to  actually  print  something.  Let’s  write  a 
program  that  prints  one  page  of  text  and  graphics.  We’ll  start  with  the  method  shown  in  the 
FORMFEED  program  and  then  add  some  enhancements.  We’ll  be  looking  at  four  versions 
of  this  program  called  PRINT1,  PRINT2,  PRINT3,  and  PRINT4.  To  avoid  a  lot  of  duplicated 
source  code,  each  of  these  programs  will  use  functions  contained  in  the  PRINT.C  file, 
which  is  shown  in  Figure  13-5. 


PRINT.C 


/* . . . - . 

PRINT.C  --  Common  Routines  for  Printl,  Print2,  Print3,  and  Print4 
(c)  Charles  Petzold,  1992 


*/ 


#include  <windows.h> 

#include  <string.h> 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

BOOL  PrintMyPage  (HWND)  ; 

extern  HANDLE  hlnst  ; 
extern  char  szAppName  []  ; 
extern  char  szCaption  []  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

Figure  15-5.  The  PRINT.C  file  ofthePRINTl,  PRINT2,  PRINT3,  (continued) 

and  PRINT4  programs. 
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if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass.lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass. hbrBackground 
wndclass. IpszMenuName 
wndclass. 1 pszCl assName 


CS_HREDRAW  !  CSJ/REDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (NULL.  IDI_APPLICATION)  ; 
LoadCursor  (NULL.  IDC_ARR0W)  ; 
GetStockObject  (WHITE_BRUSH)  ; 

NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hlnst  =  hlnstance  ; 


hwnd  =  CreateWindow  (szAppName,  szCaption, 

WS_0V  ERLAPP EDW I NDOW , 

CW_USEDEFAULT,  CW_USEDEFAULT, 

CW_USEDEFAULT,  CWJJSEDEFAULT, 

NULL.  NULL,  hlnstance.  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

HDC  GetPrinterDC  (void) 

{ 

static  char  szPrinter  [80]  ; 

char  *szDevice,  *szDriver,  *szOutput  ; 

GetProfileString  ("windows",  "device",  szPrinter,  80)  ; 

if  (NULL  !=  (szDevice  =  strtok  (szPrinter,  ”,"  ))  && 

NULL  !=  (szDriver  =  strtok  (NULL,  ",  "))  && 

NULL  !=  (szOutput  =  strtok  (NULL,  ",  "))) 

return  CreateDC  (szDriver,  szDevice,  szOutput.  NULL)  ; 

return  0  ; 

} 
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void  PageGDICalls  (HDC  hdcPrn,  short  cxPage,  short  cyPage) 

{ 

static  char  szTextStr  []  =  "Hello,  Printer!"  ; 

Rectangle  (hdcPrn,  0,  0,  cxPage,  cyPage)  ; 

MoveTo  (hdcPrn,  0,  0)  ; 

LineTo  (hdcPrn,  cxPage,  cyPage)  ; 

MoveTo  (hdcPrn,  cxPage,  0)  ; 

LineTo  (hdcPrn,  0,  cyPage)  ; 

SaveDC  (hdcPrn)  ; 

SetMapMode  (hdcPrn,  MM_IS0TR0PIC)  ; 

SetWindowExt  (hdcPrn,  1000,  1000)  ; 

SetViewportExt  (hdcPrn,  cxPage  /  2,  -cyPage  /  2)  ; 

SetViewportOrg  (hdcPrn,  cxPage  /  2,  cyPage  /  2)  ; 

Ellipse  (hdcPrn,  -500,  500,  500,  -500)  ; 

SetTextAlign  (hdcPrn,  TA.BASELINE  !  TA_CENTER)  ; 

TextOut  (hdcPrn,  0,  0,  szTextStr,  sizeof  szTextStr  -  1)  ; 

RestoreDC  (hdcPrn,  -1)  ; 

} 

long  FAR  PASCAL  ^export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  short  cxClient,  cyClient  ; 

HDC  hdc  ; 

HMENU  hMenu  ; 

PAINTSTRUCT  ps  ; 

switch  (message) 

{ 

case  WM_CREATE  : 

hMenu  =  GetSystemMenu  (hwnd,  FALSE)  ; 

AppendMenu  (hMenu,  MF.SEPARATOR,  0,  NULL)  ; 

AppendMenu  (hMenu,  0,  1,  "&Print")  ; 
return  0  ; 

case  WM_SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HIWORD  (IParam)  ; 
return  0  ; 

case  WM_SYSCOMMAND  : 
if  (wParam  ==  1) 

{ 


(continued) 
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if  (PrintMyPage  ( hwnd ) ) 

MessageBox  (hwnd,  ’’Could  not  print  page". 

szAppName,  MB_0K  !  MB_ICONEXCLAMATION )  ; 

return  0  ; 

} 

break  ; 

case  WM.PAINT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

PageGDICal 1 s  (hdc,  cxClient,  cyClient)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


PRINT.C  contains  the  functions  WinMain ,  WndProc ,  and  GetPrinterDC  and  a  function 
called  PageGDICalls ,  which  expects  to  receive  a  handle  to  the  printer  device  context  and 
two  variables  containing  the  width  and  height  of  the  printer  page.  PageGDICalls  draws  a 
rectangle  that  encompasses  the  entire  page,  two  lines  between  opposite  corners  of  the 
page,  an  ellipse  in  the  middle  of  the  page  (its  diameter  half  the  lesser  of  the  printer  height 
and  width),  and  the  text  “Hello,  Printer!”  in  the  center  of  this  ellipse. 

During  processing  of  the  WM-CREATE  message,  WndProc  adds  a  Print  option  to  the 
system  menu.  Selecting  this  option  causes  a  call  to  PrintMyPage ,  a  function  that  we’ll 
enhance  over  the  course  of  the  four  versions  of  the  program.  PrintMyPage  returns  TRUE 
(nonzero)  if  it  encounters  an  error  during  printing  and  returns  FALSE  otherwise.  If 
PrintMyPage  returns  TRUE,  WndProc  displays  a  message  box  to  inform  you  of  the  error. 

Bare-Bones  Printing 

PRINTl,  the  first  version  of  the  printing  program,  is  shown  in  Figure  15-6.  After  compiling 
PRINT1,  you  can  execute  it  and  then  select  Print  from  the  system  menu.  If  your  WIN.INI 
file  has  the  line  Spooler  =yes  and  if  Windows  can  find  PRINTMAN.EXE,  you  should  see  the 
Print  Manager  icon  appear  at  the  bottom  of  the  screen.  If  the  TEMP  variable  in  your  MS- 
DOS  environment  indicates  a  fixed  disk  (or  if  you  have  no  TEMP  variable),  then  you  should 
see  some  disk  activity  as  the  GDI  module  saves  the  printer  output  to  a  temporary  file.  You 
won’t  be  able  to  do  anything  in  Windows  during  this  time.  After  PRINTl  has  finished,  the 
Print  Manager  should  display  the  text  “Printl:  Printing”  in  its  client  area  and  begin  sending 
the  disk  file  out  to  the  printer.  You’ll  be  able  to  work  normally  in  Windows  again. 
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Let’s  look  at  the  code  in  PRINT1.C.  If  PrintMyPage  can’t  obtain  a  device  context 
handle  for  the  printer,  it  returns  TRUE,  and  WndProc  displays  the  message  box  indicating 
an  error.  If  the  function  succeeds  in  obtaining  the  device  context  handle,  it  then  deter¬ 
mines  the  horizontal  and  vertical  size  of  the  page  in  pixels  by  calling  GetDeviceCaps : 

xPage  =  GetDeviceCaps  (hdcPrn,  HORZRES)  ; 
yPage  =  GetDeviceCaps  (hdcPrn,  VERTRES)  ; 

This  is  not  the  full  size  of  the  paper  but  rather  its  printable  area.  After  that  call,  the  code  in 
PRINTl’s  PrintMyPage  function  is  structurally  the  same  as  the  code  in  FORMFEED,  except 
that  PRINT1  calls  PageGDICalls  between  the  STARTDOC  and  NEWFRAME  Escape  calls. 
Only  if  both  the  STARTDOC  and  NEWFRAME  calls  are  successful  does  PRINT1  call  END- 
DOC  Escape. 


PRINT1.MAK 

# . 

#  PRINTl.MAK  make  file 

#  . 

printl.exe  :  print. obj  printl.obj  printl.def 

$(WINLINK)  printl  print,  printl,  NUL,  $(WINLIB),  printl 
rc  -t  printl.exe 

print. obj  :  print. c 
$(WINCC)  print. c 

printl.obj  :  printl. c 
$ ( W I NCC )  printl. c 


PR1NT1.C 

/* . . . 

PRINTl.C  --  Bare-Bones  Printing 

(c)  Charles  Petzold,  1992 
. - . */ 

#include  <windows.h> 

HDC  GetPrinterDC  (void)  ;  //  in  PRINT. C 

void  PageGDICalls  (HDC,  short,  short)  ; 

HANDLE  hlnst  ; 

char  szAppName  []  =  "Printl"  ; 

char  szCaption  []  =  "Print  Program  1"  ; 


Figure  15-6.  The  PRINT1  program. 


(continued) 
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BOOL  PrintMyPage  ( HWND  hwnd) 

{ 

static  char  szMessage  []  =  "Printl:  Printing"  ; 

BOOL  bError  =  FALSE  ; 

HDC  hdcPrn  ; 

short  xPage,  yPage  ; 

if  (NULL  ==  (hdcPrn  =  GetPrinterDC  ())) 
return  TRUE  ; 

xPage  =  GetDeviceCaps  (hdcPrn,  HORZRES)  ; 
yPage  =  GetDeviceCaps  (hdcPrn,  VERTRES)  ; 

if  (Escape  (hdcPrn,  STARTDOC,  sizeof  szMessage  -  1,  szMessage,  NULL)  >  0) 
{ 

PageGDICalls  (hdcPrn,  xPage,  yPage)  ; 

if  (Escape  (hdcPrn,  NEWFRAME,  0,  NULL,  NULL)  >  0) 

Escape  (hdcPrn,  ENDDOC,  0,  NULL,  NULL)  ; 

else 

bError  =  TRUE  ; 

} 

else 

bError  =  TRUE  ; 

DeleteDC  (hdcPrn)  ; 
return  bError  ; 

} 


PRINT1  .DEF 


PRINTl.DEF  module  definition  file 


NAME  PRINT1 


DESCRIPTION  'Printing  Program  No.  1  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 
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Setting  an  Abort  Procedure 

The  enhancement  that  we’ll  add  in  the  PRINT2  version  of  our  program  prevents  problems 
related  to  disk  space.  If  you  try  to  run  PRINT1  when  the  drive  containing  the  TEMP  subdi¬ 
rectory  lacks  sufficient  space  to  store  the  full  page  of  graphics  output,  the  NEWFRAME 
Escape  call  will  return  an  SP_OUTOFDISK  error.  This  error  could  result  from  the  presence 
in  the  TEMP  subdirectory  of  other  temporary  print  files  created  by  GDI  for  printing.  If  the 
Print  Manager  were  given  enough  time  to  send  these  files  to  the  printer,  then  the  program 
currently  printing  could  continue.  It  wouldn’t  be  necessary  for  Windows  to  return  an  SP- 
-OUTOFDISK  error  to  the  program.  However,  the  Print  Manager  cannot  transfer  these  files 
to  the  printer  because — like  all  other  Windows  programs — it  isn’t  receiving  messages  dur¬ 
ing  the  time  your  program  is  printing. 

This  problem  is  solved  with  something  called  an  “abort  procedure.”  The  abort  pro¬ 
cedure  is  a  small  exported  function  in  your  program.  You  give  Windows  the  address  of  this 
function  using  the  Escape  SETABORTPROC  subfunction.  If  GDI  runs  out  of  disk  space 
while  creating  temporary  print  files,  and  if  enough  space  could  eventually  be  made  avail¬ 
able  by  having  the  Print  Manager  send  existing  print  files  to  the  printer,  then  the  GDI  mod¬ 
ule  calls  the  program’s  abort  procedure.  The  abort  procedure  then  effectively  yields 
control  to  allow  the  Print  Manager  to  print. 

Let’s  look  first  at  what’s  required  to  add  an  abort  procedure  to  the  printing  logic  and 
then  examine  some  of  the  ramifications.  The  abort  procedure  is  commonly  called 
AbortProc ,  and  it  takes  the  following  form: 

BOOL  FAR  PASCAL  .export  AbortProc  (HDC  hdcPrn,  short  nCode) 

{ 

[other program  lines] 

} 

Before  printing,  you  must  obtain  a  pointer  to  this  function  from  MakeProcInstance : 

FARPROC  lpfnAbortProc  ; 

[other program  lines] 

lpfnAbortProc  =  MakeProcInstance  (AbortProc,  hlnstance)  ; 

You  then  set  the  abort  procedure  using  the  Escape  SETABORTPROC  subfunction.  The 
IpsDataln  parameter  is  the  pointer  returned  from  MakeProcInstance : 

Escape  (hdcPrn,  SETABORTPROC,  0,  ( LPSTR)  lpfnAbortProc,  NULL)  ; 

You  make  this  call  before  the  STARTDOC  Escape  call.  You  don’t  need  to  “unset”  the  abort 
procedure  after  you  finish  printing. 

While  processing  the  NEWFRAME  Escapee  all  (that  is,  while  playing  the  metafile  into 
the  device  driver  and  creating  the  temporary  printer  output  files),  GDI  frequently  calls  the 
abort  procedure.  The  hdcPrn  parameter  is  the  printer  device  context  handle.  The  nCode 
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parameter  is  0  if  all  is  going  well  or  is  SP_OUTOFDISK  if  the  GDI  module  has  run  out  of 
disk  space  because  of  the  temporary  printer  output  files. 

AbortProc  must  return  TRUE  (nonzero)  if  the  print  job  is  to  be  continued  and  returns 
FALSE  (0)  if  the  print  job  is  to  be  aborted.  If  AbortProc  receives  an  nCode  parameter  of  SP- 
-OUTOFDISK  and  returns  FALSE,  then  the  NEWFRAME  Escape  call  currently  in  progress 
returns  an  SP_  APPABORT  error  code  (equal  to  -2),  and  the  print  job  is  aborted. 

The  abort  procedure  can  be  as  simple  as  this: 

BOOL  FAR  PASCAL  _export  AbortProc  (HDC  hdcPrn,  short  nCode) 

{ 

MSG  msg  ; 

while  (PeekMessage  (&msg,  NULL,  0,  0,  PM_REM0VE ) ) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  TRUE  ; 

} 

This  function  may  seem  a  little  peculiar.  In  fact,  it  looks  suspiciously  like  a  message  loop. 
What’s  a  message  loop  doing  here  of  all  places?  Well,  it  is  a  message  loop.  You’ll  note,  how¬ 
ever,  that  this  message  loop  calls  PeekMessage  rather  than  GetMessage.  I  discussed  Peek- 
Message  in  connection  with  the  RANDRECT  program  at  the  end  of  Chapter  12.  You’ll  recall 
that  PeekMessage  returns  control  to  a  program  with  a  message  from  the  program’s  message 
queue  (just  like  GetMessage)  but  also  returns  control  if  there  are  no  messages  waiting  in 
any  program’s  message  queue. 

The  message  loop  in  the  AbortProc  function  repeatedly  calls  PeekMessage  while 
PeekMessage  returns  TRUE.  This  TRUE  value  means  that  PeekMessage  has  retrieved  a  mes¬ 
sage  that  can  be  sent  to  one  of  the  program’s  window  procedures  using  TranslateMessage 
and  DispatchMessage.  When  there  are  no  more  messages  in  the  program’s  message  queue, 
Windows  allows  other  programs  to  process  messages  from  their  queues.  When  there  are 
no  more  messages  in  any  program’s  message  queue,  Windows  returns  control  to  the  pro¬ 
gram  calling  PeekMessage  (that  is,  to  the  AbortProc  function).  The  return  value  of  Peek- 
Message  is  then  FALSE,  so  AbortProc  returns  control  to  Windows. 

The  PRINT1  version  of  our  program  doesn’t  yield  control  during  the  entire  time  it  is 
printing.  Windows  is  essentially  frozen  during  that  time  because  no  other  program  can 
process  messages.  As  you’ve  probably  discovered  by  now,  the  PrintMyPage  function  in 
PRINT1  can  take  a  while.  Only  when  the  function  is  finished  can  the  Print  Manager  actually 
start  to  print.  An  abort  procedure  gives  the  Print  Manager — and  other  programs  running 
under  Windows — a  chance  to  run  while  a  program  is  printing. 
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How  Windows  Uses  AbortProc 

When  a  program  is  printing,  the  bulk  of  the  work  takes  place  during  the  NEWFRAME 
Escapee  all.  Before  that  call,  the  GDI  module  simply  adds  another  record  to  the  disk-based 
metafile  every  time  the  program  calls  a  GDI  drawing  function.  When  GDI  gets  the 
NEWFRAME  Escape  call,  it  plays  this  metafile  into  the  device  driver  once  for  each  band  the 
device  driver  defines  on  a  page.  GDI  then  stores  in  a  file  the  printer  output  created  by  the 
printer  driver.  If  the  Print  Manager  isn’t  loaded,  the  GDI  module  itself  must  write  this 
printer  output  to  the  printer. 

During  the  NEWFRAME  Escape  call,  the  GDI  module  calls  the  abort  procedure 
you’ve  set.  Normally,  the  nCode  parameter  is  0,  but  if  GDI  has  run  out  of  disk  space  be¬ 
cause  of  the  presence  of  other  temporary  files  that  haven’t  been  printed  yet,  then  the 
nCode  parameter  is  SP_OUTOFDISK.  (You  wouldn’t  normally  check  this  value,  but  you  can 
if  you  want.)  The  abort  procedure  then  goes  into  its  PeekMessage  loop.  The  loop  first 
retrieves  messages  from  the  program’s  own  message  queue  and  then  yields  control  so  that 
other  programs  can  retrieve  and  process  their  own  messages.  When  no  messages  remain 
in  any  program’s  queue,  control  passes  to  another  program  currently  waiting  for  its  own 
PeekMessage  c all  to  return. 

One  of  those  programs  is  PRINTMAN.EXE,  which  also  uses  a  PeekMessage  call  to 
retrieve  messages.  When  the  Print  Manager  returns  from  the  PeekMessage  call  in  its  own 
message  loop,  it  can  transfer  part  of  a  disk  file  to  the  printer.  The  Print  Manager  then  calls 
PeekMessage  again  in  its  own  message  loop.  If  there  are  still  no  messages  in  any  program’s 
message  queue,  control  returns  to  AbortProc ,  and  PeekMessage  returns  FALSE.  The  abort 
procedure  then  drops  out  of  its  message  loop  and  returns  a  TRUE  value  to  the  GDI  module 
to  indicate  that  printing  should  continue.  The  GDI  module  then  continues  to  process  the 
NEWFRAME  Escape  call. 

While  the  main  purpose  of  the  abort  procedure  is  to  allow  the  Print  Manager  the  op¬ 
portunity  to  transfer  existing  files  to  the  printer  to  free  up  disk  space,  it  also  allows  all  other 
programs  to  run  during  the  time  a  program  is  printing.  This  effect  of  the  abort  procedure  is 
particularly  important  if  the  Print  Manager  isn’t  installed. 

Implementing  an  Abort  Procedure 

Let’s  quickly  review  the  mechanics  of  the  abort  procedure.  You  define  an  abort  procedure 
that  looks  like  this: 

BOOL  FAR  PASCAL  .export  AbortProc  (HDC  hdcPrn ,  short  nCode) 

{ 

MSG  msg  ; 

while  (PeekMessage  (&msg,  NULL.  0,  0,  PM.REMOVE)) 

{ 
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TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  TRUE  ; 

} 

You  obtain  a  pointer  to  the  function  using  MakeProcInstance : 

1 pfnAbortProc  =  MakeProcInstance  (AbortProc,  hlnstance)  ; 

When  you  want  to  print  something,  you  give  Windows  this  pointer  with  an  Escapee  all: 

Escape  (hdcPrn,  SETABORTPROC,  0,  ( LPSTR)  1 pfnAbortProc,  NULL)  ; 

You  make  this  Escapee  all  before  the  Escape  call  for  STARTDOC.  And  that’s  it. 

Well,  not  quite.  We’ve  overlooked  a  problem  with  that  PeekMessage  loop  in 
AbortProc — a  big  problem.  AbortProc  is  called  only  while  your  program  is  in  the  midst  of 
printing.  Some  very  ugly  things  can  happen  if  you  retrieve  a  message  in  AbortProc  and  dis¬ 
patch  it  to  your  own  window  procedure.  A  user  could  select  Print  from  the  menu  again.  But 
the  program  is  already  in  the  middle  of  the  printing  routine.  A  user  could  load  a  new  file 
into  the  program  while  the  program  is  trying  to  print  the  previous  file.  A  user  could  even 
quit  your  program!  If  that  happens,  all  your  program’s  windows  will  be  destroyed.  You’ll 
eventually  return  from  the  printing  routine,  but  you’ll  have  nowhere  to  go  except  to  a 
window  procedure  that’s  no  longer  valid. 

This  stuff  boggles  the  mind.  Your  program  isn’t  prepared  for  it.  For  this  reason,  when 
you  set  an  abort  procedure,  you  should  first  disable  your  program’s  window  so  that  it  can’t 
receive  keyboard  and  mouse  input.  You  do  this  with: 

EnableWindow  (hwnd,  FALSE)  ; 

This  prevents  keyboard  and  mouse  input  from  getting  into  the  message  queue.  The  user 
therefore  can’t  do  anything  with  your  program  during  the  time  it’s  printing.  When  printing 
is  finished,  you  reenable  the  window  for  input: 

EnableWindow  (hwnd,  TRUE)  ; 

So  why,  you  ask,  do  we  even  bother  with  the  TranslateMessage  and  DispatchMessage 
calls  in  AbortProc  when  no  keyboard  or  mouse  messages  will  get  into  the  message  queue 
in  the  first  place?  It’s  true  that  the  TranslateMessage  call  isn’t  strictly  needed  (although  it’s 
almost  always  included).  But  we  must  use  DispatchMessage  in  case  a  WM_PAINT  message 
gets  in  the  message  queue.  If  WM_PAINT  isn’t  processed  properly  with  a  BeginPaint  and 
EndPaint  pair  in  the  window  procedure,  the  message  will  remain  in  the  queue  and  clog  up 
the  works,  because  PeekMessage  will  never  return  a  FALSE. 

When  you  disable  your  window  during  the  time  you’re  printing,  your  program 
remains  inert  on  the  display.  But  a  user  can  switch  to  another  program  and  do  some  work 
there,  and  Print  Manager  can  continue  sending  output  files  to  the  printer. 


760 


Chapter  15:  Using  the  Printer 


The  PRINT2  program,  shown  in  Figure  15-7,  adds  an  abort  procedure  (and  the  neces¬ 
sary  support)  to  the  logic  in  PRINT!  More  specifically,  PRINT2  adds  the  abort  procedure 
(including  a  listing  in  the  EXPORTS  section  of  PRINT2.DEF),  a  call  to  MakeProcInstance 
and  Escape  using  the  SETABORTPROC  subfunction,  a  FreeProcInstance  call  at  the  end, 
and  two  calls  to  EnableWindow ,  the  first  to  disable  the  window  and  the  second  to  re¬ 
enable  it. 


PRINT2.MAK 

# . 

#  PRINT2.MAK  make  file 

#  . 

print2.exe  :  print. obj  print2.obj  print2.def 

$(WINLINK)  print2  print,  print2,  NUL,  $(WINLIB),  print2 
rc  -t  print2.exe 

print. obj  :  print. c 
$(WINCC)  print. c 

print2.obj  :  print2.c 
$ ( WI NCC )  print2.c 


PRINT2.C 

/* . 

PRINT2.C  --  Printing  with  Abort  Function 
(c)  Charles  Petzold,  1992 
. */ 

#include  <windows.h> 

HDC  GetPrinterDC  (void)  ;  //  in  PRINT. C 

void  PageGDICal 1 s  (HDC,  short,  short)  ; 

HANDLE  hlnst  ; 

char  szAppName  []  =  ,,Print2"  ; 

char  szCaption  []  =  "Print  Program  2  (Abort  Function)"  ; 

BOOL  FAR  PASCAL  ..export  AbortProc  (HDC  hdcPrn,  short  nCode) 
{ 

MSG  msg  ; 


Figure  15-7.  The  PRINT2 program . 


(continued) 
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while  (PeekMessage  (&msg,  NULL,  0,  0,  PM_REM0VE) ) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  TRUE  ; 

} 

BOOL  PrintMyPage  (HWND  hwnd) 

{ 

static  char  szMessage  []  =  "Print2:  Printing"  ; 

BOOL  bError  =  FALSE  ; 

FARPROC  lpfnAbortProc  ; 

HDC  hdcPrn  ; 

short  xPage,  yPage  ; 

if  (NULL  ==  (hdcPrn  =  GetPrinterDC  ())) 
return  TRUE  ; 

xPage  =  GetDeviceCaps  (hdcPrn,  HORZRES)  ; 
yPage  =  GetDeviceCaps  (hdcPrn,  VERTRES)  ; 

EnableWindow  (hwnd,  FALSE)  ; 

lpfnAbortProc  =  MakeProcInstance  ((FARPROC)  AbortProc,  hlnst)  ; 

Escape  (hdcPrn,  SETABORTPROC,  0,  ( LPSTR)  lpfnAbortProc,  NULL)  ; 

if  (Escape  (hdcPrn,  STARTDOC,  sizeof  szMessage  ■  1,  szMessage,  NULL)  >  0) 

{ 

PageGDICalls  (hdcPrn,  xPage,  yPage)  ; 

if  (Escape  (hdcPrn,  NEWFRAME,  0,  NULL,  NULL)  >  0) 

Escape  (hdcPrn,  ENDDOC,  0,  NULL,  NULL)  ; 

else 

bError  =  TRUE  ; 

} 

else 

bError  =  TRUE  ; 
if  (IbError) 

Escape  (hdcPrn,  ENDDOC,  0,  NULL,  NULL)  ; 

FreeProcInstance  (lpfnAbortProc)  ; 

EnableWindow  (hwnd,  TRUE)  ; 

DeleteDC  (hdcPrn)  ; 
return  bError  ; 

} 
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PRINT2.DEF 


9 

;  PRINT2.DEF  module  definition  file 


NAME  PRINT2 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Printing  Program  No.  2  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


Adding  a  Printing  Dialog  Box 

PRINT2  is  not  entirely  satisfactory.  First,  the  program  doesn’t  directly  indicate  when  it  is 
printing  and  when  it  is  finished  with  printing.  Only  when  you  poke  at  the  program  with 
the  mouse  and  find  that  it  doesn’t  respond  can  you  determine  that  it  must  still  be  process¬ 
ing  the  PrintMyPage  routine.  Nor  does  PRINT2  give  the  user  the  opportunity  to  cancel  the 
print  job  before  it  shows  up  in  the  Print  Manager’s  client  area. 

You’re  probably  aware  that  most  Windows  programs  give  users  a  chance  to  cancel  a 
printing  operation  currently  in  progress.  A  small  dialog  box  comes  up  on  the  screen;  it 
contains  some  text  and  a  push  button  labeled  Cancel.  The  program  displays  this  dialog  box 
during  the  entire  time  that  GDI  is  saving  the  printer  output  in  a  disk  file  or  (if  the  Print 
Manager  isn’t  loaded)  while  the  printer  is  printing.  This  is  a  modeless  dialog  box,  and 
you  must  supply  the  dialog  procedure.  As  for  all  dialog  boxes,  you  use  MakeProcInstance 
to  obtain  a  pointer  to  the  function. 

This  dialog  box  is  often  called  the  “abort  dialog  box,”  and  the  dialog  procedure  is 
often  called  the  “abort  dialog  procedure.”  To  distinguish  it  more  clearly  from  the  “abort 
procedure,”  I’ll  call  this  dialog  procedure  the  “printing  dialog  procedure.”  The  abort  pro¬ 
cedure  (with  the  name  AbortProc )  and  the  printing  dialog  procedure  (which  I’ll  name 
PrintDlgProc )  are  two  separate  exported  functions.  If  you  want  to  print  in  a  professional 
Windows-like  manner,  you  must  have  both  of  these. 

These  two  functions  interact  as  follows.  The  PeekMessage  loop  in  AbortProc  must  be 
modified  to  send  messages  for  the  modeless  dialog  box  to  the  dialog  box  window  pro¬ 
cedure.  PrintDlgProc  must  process  WM -COMMAND  messages  to  check  the  status  of  the 
Cancel  button.  If  the  Cancel  button  is  pressed,  it  sets  a  variable  called  bUserAbort  to  TRUE. 
The  value  returned  from  AbortProc  is  the  inverse  of  bUserAbort.  You  will  recall  that 
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AbortProc  returns  TRUE  to  continue  printing  and  FALSE  to  abort  printing.  In  PRINT2  we 
always  returned  TRUE.  Now  well  return  FALSE  if  the  user  clicks  the  Cancel  button  in  the 
printing  dialog  box.  This  logic  is  implemented  in  the  PRINT3  program,  shown  in  Figure 
15-8. 


PRINT3.MAK 

# 

#  PRINT3.MAK  make  file 

#  . 

print3.exe  :  print. obj  print3.obj  print3.def  print. res 

$( WINLINK)  print3  print,  print3,  NUL,  $(WINLIB),  print3 
rc  -t  print. res  print3.exe 

print. obj  :  print. c 
$ ( WI NCC )  print. c 

print3.obj  :  print3.c 
$ ( WI NCC )  print3.c 

print. res  :  print. rc 
$ ( WI N RC )  print. rc 


PRINT3.C 

/* . . - . 

PRINT3.C  --  Printing  with  Dialog  Box 
(c)  Charles  Petzold,  1992 
. - . */ 


^include  <windows.h> 

HDC  GetPrinterDC  (void)  ;  //  in  PRINT. C 

void  PageGDICalls  (HDC,  short,  short)  ; 

HANDLE  hlnst  ; 

char  szAppName  []  =  "Print3"  ; 

char  szCaption  []  =  "Print  Program  3  (Dialog  Box)"  ; 

BOOL  bllserAbort  ; 

HWND  hDlgPrint  ; 


Figure  15-8.  The  PRINT3  program. 


(continued) 
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BOOL  FAR  PASCAL  .export  PrintDlgProc  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM.INITDIALOG  : 

SetWindowText  (hDlg,  szAppName)  ; 

EnableMenuItem  (GetSystemMenu  (hDlg,  FALSE),  SC.CLOSE, 

MF.GRAYED)  ; 

return  TRUE  ; 

case  WM.COMMAND  : 

bUserAbort  =  TRUE  ; 

EnableWindow  (GetParent  (hDlg).  TRUE)  ; 

DestroyWindow  (hDlg)  ; 
hDlgPrint  =  0  ; 
return  TRUE  ; 

} 

return  FALSE  ; 

} 

BOOL  FAR  PASCAL  .export  AbortProc  (HDC  hdcPrn,  short  nCode) 

{ 

MSG  msg  ; 

while  UbUserAbort  &&  PeekMessage  (&msg,  NULL,  0,  0,  PM.REMOVE) ) 

{ 

if  (IhDlgPrint  !!  I IsDi al ogMessage  (hDlgPrint,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

return  IbUserAbort  ; 

} 

BOOL  PrintMyPage  (HWND  hwnd) 

{ 

static  char  szMessage  []  =  "Print3:  Printing"  ; 

BOOL  bError  =  FALSE  ; 

FARPROC  lpfnAbortProc,  1 pfnPri ntDl gProc  ; 

HDC  hdcPrn  ; 

short  xPage,  yPage  ; 

if  (NULL  ==  (hdcPrn  =  GetPrinterDC  ())) 
return  TRUE  ; 

xPage  =  GetDeviceCaps  (hdcPrn,  HORZRES)  ; 
yPage  =  GetDeviceCaps  (hdcPrn,  VERTRES)  ; 


(continued) 
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EnableWindow  (hwnd,  FALSE)  ; 
bUserAbort  =  FALSE  ; 

IpfnPrintDlgProc  =  MakeProcInstance  ( ( FARPROC )  PrintDlgProc,  hlnst)  ; 
hDlgPrint  =  CreateDialog  (hlnst,  "PrintDl gBox",  hwnd,  IpfnPrintDlgProc)  ; 

IpfnAbortProc  =  MakeProcInstance  ((FARPROC)  AbortProc,  hlnst)  ; 

Escape  (hdcPrn,  SETABORTPROC,  0,  ( LPSTR)  IpfnAbortProc,  NULL)  ; 

if  (Escape  (hdcPrn,  STARTDOC,  sizeof  szMessage  -  1,  szMessage,  NULL)  >  0) 
{ 

PageGDICalls  (hdcPrn,  xPage,  yPage)  ; 

if  (Escape  (hdcPrn,  NEW  FRAME ,  0,  NULL,  NULL)  >  0) 

Escape  (hdcPrn,  ENDDOC,  0,  NULL,  NULL)  ; 

else 

bError  =  TRUE  ; 

} 

else 

bError  =  TRUE  ; 

if  ( IbUserAbort) 

{ 

EnableWindow  (hwnd,  TRUE)  ; 

DestroyWindow  (hDlgPrint)  ; 

} 

FreeProcInstance  (IpfnPrintDlgProc)  ; 

FreeProcInstance  (IpfnAbortProc)  ; 

DeleteDC  (hdcPrn)  ; 

return  bError  : !  bUserAbort  ; 

} 


PRINT.RC 

/* . . . . 

PRINT.RC  resource  script 

*/ 


#include  <windows.h> 

PrintDl gBox  DIALOG  40,  40,  120,  40 

STYLE  WS.POPUP  !  WS.CAPTION  !  WS.SYSMENU  !  WSJ/ISIBLE 
{ 

CTEXT  "Cancel  Printing",  -1,  4,  6,  120,  12 

DEFPUSHBUTTON  "Cancel",  IDCANCEL,  44,  22,  32,  14,  WS_GR0UP 
} 
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PRINT3.DEF 


PRINT3 . DEF  module  definition  file 


NAME 


PRINT3 


DESCRIPTION  'Printing  Program  No.  3  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


Two  global  variables  are  added  to  PRINT3:  a  BOOL  called  bUserAbort  and  a  handle  to  the 
dialog  box  window  called  hDlgPrint.  The  PrintMyPage  function  initializes  bUserAbort  to 
FALSE,  and  as  in  PRINT2,  the  program’s  main  window  is  disabled.  PrintMyPage  then  calls 
MakeProcInstance  for  both  AbortProc  and  PrintDlgProc.  The  pointer  to  AbortProc  is  used 
in  the  SETABORTPROC  Escape  call,  and  the  pointer  to  PrintDlgProc  is  used  in  a  Create- 
Dialog  call.  The  window  handle  returned  from  CreateDialog  is  saved  in  hDlgPrint. 

The  message  loop  in  AbortProc  now  looks  like  this: 

while  ( IbUserAbort  &&  PeekMessage  (&msg,  NULL,  0,  0,  PM_REM0VE) ) 

{ 

if  (IhDlgPrint  !!  ! IsDi al ogMessage  (hDlgPrint,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

return  IbUserAbort  ; 

It  calls  PeekMessage  only  if  bUserAbort  is  FALSE,  that  is,  if  the  user  hasn’t  yet  aborted  the 
printing  operation.  The  IsDialogMessage  function  is  required  to  send  the  message  to  the 
modeless  dialog  box.  As  is  normal  with  modeless  dialog  boxes,  the  handle  to  the  dialog  box 
window  is  checked  before  this  call  is  made.  AbortProc  returns  the  inverse  of  bUserAbort. 
Initially,  bUserAbort  is  FALSE,  so  AbortProc  returns  TRUE,  indicating  that  printing  is  to 
continue.  But  bUserAbort  could  be  set  to  TRUE  in  the  printing  dialog  procedure. 

The  PrintDlgProc  function  is  fairly  simple.  While  processing  WM_INITDIALOG, 
the  function  sets  the  window  caption  to  the  name  of  the  program  and  disables  the  Close 
option  on  the  system  menu.  If  the  user  clicks  the  Cancel  button,  PrintDlgProc  receives 
a  WM-COMMAND  message: 
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case  WM_COMMAND  : 

bUserAbort  =  TRUE  ; 

EnableWindow  (GetParent  (hDlg),  TRUE)  ; 

DestroyWindow  (hDlg)  ; 
hDlgPrint  =  0  ; 
return  TRUE  ; 

Setting  bUserAbort  to  TRUE  indicates  that  the  user  has  decided  to  cancel  the  printing 
operation.  The  main  window  is  enabled,  and  the  dialog  box  is  destroyed.  (It  is  important 
that  you  perform  these  two  actions  in  this  order.  Otherwise,  some  other  program  running 
under  Windows  will  become  the  active  program,  and  your  program  might  disappear  into 
the  background.)  As  is  normal,  hDlgPrint  is  set  to  0  to  prevent  IsDialogMessage  from  be¬ 
ing  called  in  the  message  loop. 

The  only  time  this  dialog  box  receives  messages  is  when  AbortProc  retrieves  mes¬ 
sages  with  PeekMessage  and  sends  them  to  the  dialog  box  window  procedure  with 
IsDialogMessage.  The  only  time  AbortProc  is  called  is  when  the  GDI  module  is  processing 
the  NEWFRAME  Escape  function.  If  GDI  sees  that  the  return  value  from  AbortProc  is 
FALSE,  it  returns  control  from  the  Escape  call  back  to  PrintMyPage.  It  doesn’t  return  an 
error  code.  At  that  point,  PrintMyPage  thinks  that  the  page  is  complete  and  calls  the 
ENDDOC  Escape  function.  Nothing  is  printed,  however,  because  the  GDI  module  didn’t 
finish  processing  the  NEWFRAME  Escape  call. 

Some  cleanup  remains.  If  the  user  didn’t  cancel  the  print  job  from  the  dialog  box, 
then  the  dialog  box  is  still  displayed.  PrintMyPage  reenables  its  main  window  and  destroys 
the  dialog  box: 

if  ( IbUserAbort) 

{ 

EnableWindow  (hwnd,  TRUE)  ; 

DestroyWindow  (hDlgPrint)  ; 

} 

Two  variables  tell  you  what  happened:  bUserAbort  tells  you  if  the  user  aborted  the 
print  job,  and  bError  tells  you  if  an  error  occurred.  You  can  do  what  you  want  with  these 
variables.  PrintMyPage  simply  performs  a  logical  OR  operation  to  return  to  WndProc. 

return  bError  ! !  bUserAbort  ; 

Adding  Printing  to  POPPAD 

Now  we’re  ready  to  add  a  printing  facility  to  the  POPPAD  series  of  programs  and  declare 
POPPAD  finished.  You’ll  need  the  various  POPPAD  files  from  Chapter  10,  plus  the  two  new 
files  in  Figure  15-9. 
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POPPAD.MAK 

# . . 

#  POPPAD.MAK  make  file 

poppad.exe  :  poppad.obj  popfile.obj  popfind.obj  \ 

popfont.obj  popprnt.obj  poppad.res  poppad.def 
$(WINLINK)  poppad  popfile  popfind  popfont  popprnt,  poppad  ,  V 
NUL,  $(WINLIB),  poppad 
rc  -t  poppad.res  poppad.exe 

poppad.obj  :  poppad. c  poppad. h 
$ ( WI NCC )  poppad. c 

popfile.obj  :  popfile.c 
$ ( WI NCC )  popfile.c 

popfind.obj  :  popfind.c 
$ ( WI NCC )  popfind.c 

popfont.obj  :  popfont. c 
$ ( WI NCC )  popfont. c 

popprnt.obj  :  popprnt. c 
$ ( WI NCC )  popprnt. c 

poppad.res  :  poppad. rc  poppad. h  poppad. ico 
$ ( W I NRC )  poppad. rc 


POPPRNT.C 


/* . - . - . 

POPPRNT.C  --  Popup  Editor  Printing  Functions 

. */ 


#include  <windows.h> 

#include  <commdlg.h> 

#include  <string.h> 

#include  "poppad. h" 

BOOL  bUserAbort  ; 

HWND  hDlgPrint  ; 

BOOL  FAR  PASCAL  .export  PrintDlgProc  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  IParam) 


Figure  15-9.  New  POPPAD  files  to  add  printing  capability. 


(continued) 
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switch  (message) 

{ 

case  WM_INITDIALOG  : 

EnableMenuItem  (GetSystemMenu  (hDlg,  FALSE),  SC.CLOSE, 

MF.GRAYED)  ; 

return  TRUE  ; 


case  WM_COMMAND  : 

bUserAbort  =  TRUE  ; 

EnableWindow  (GetParent  (hDlg),  TRUE)  ; 

DestroyWindow  (hDlg)  ; 
hDlgPrint  =  0  ; 
return  TRUE  ; 

} 

return  FALSE  ; 

} 

BOOL  FAR  PASCAL  .export  AbortProc  (HDC  hPrinterDC,  short  nCode) 

{ 

MSG  msg  ; 

while  ( ! bUse rAbort  &&  PeekMessage  (&msg,  NULL,  0,  0,  PM.REMOVE) ) 
{ 

if  (IhDlgPrint  !!  ! IsDi al ogMessage  (hDlgPrint,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

return  IbUserAbort  ; 

} 


BOOL  PopPrntPrintFile  (HANDLE  hlnst,  HWND  hwnd,  HWND  hwndEdit, 

LPSTR  szTitleName) 


{ 

static  PRINTDLG 

BOOL 

char 

FARPROC 

NPSTR 

short 

TEXTMETRIC 

WORD 


pd  ; 

bSuccess  ; 
szJobName  [40]  ; 

1 pfnAbortProc,  lpfnPrintDlgProc  ; 
npstrBuffer  ; 

yChar,  nCharsPerLine,  nLinesPerPage,  nTotalLines, 
nTotalPages,  nPage,  nLine,  nLineNum  ; 
tm  ; 

nColCopy,  nNonColCopy  ; 


pd.lStructSize  =  sizeof  (PRINTDLG)  ; 

pd.hwndOwner  =  hwnd  ; 


(continued) 
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pd.hDevMode 

pd.hDevNames 

pd.hDC 

pd. Flags 

pd.nFromPage 

pd.nToPage 

pd.nMinPage 

pd.nMaxPage 

pd.nCopies 

pd.hlnstance 

pd.lCustData  = 

pd.lpfnPrintHook  = 

pd.lpfnSetupHook 
pd.lpPrintTemplateName  = 
pd.lpSetupTemplateName  = 
pd.hPrintTemplate 
pd.hSetupTemplate 


NULL  ; 

NULL  ; 

NULL  ; 

PD.ALLPAGES  !  PD_COLLATE  !  PD_RETURNDC  ; 
0  ; 

0  ; 

0  ; 

0  ; 

1  ; 

NULL  ; 

0L  ; 

NULL  ; 

NULL  ; 

NULL  ; 

NULL  ; 

NULL  ; 

NULL  ; 


if  ( JPrintDlg  (&pd) ) 
return  TRUE  ; 

nTotal Lines  =  (short)  SendMessage  (hwndEdit,  EM_GETLI NECOUNT ,  0,  0L)  ; 


if  (nTotal Lines  ==  0) 
return  TRUE  ; 

GetTextMetrics  (pd.hDC,  &tm)  ; 

yChar  =  tm.tmHeight  +  tm.tmExternal Leading  ; 

nCharsPerLine  =  GetDeviceCaps  (pd.hDC,  HORZRES)  /  tm.tmAveCharWidth  ; 
nLinesPerPage  =  GetDeviceCaps  (pd.hDC,  VERTRES)  /  yChar  ; 
nTotalPages  =  (nTotalLines  +  nLinesPerPage  -  1)  /  nLinesPerPage  ; 

npstrBuffer  =  (NPSTR)  LocalAlloc  (LPTR,  nCharsPerLine  +  1)  ; 

EnableWindow  (hwnd,  FALSE)  ; 

bSuccess  =  TRUE  ; 
bUserAbort  =  FALSE  ; 

lpfnPrintDlgProc  =  MakeProcInstance  ((FARPROC)  PrintDlgProc,  hlnst)  ; 
hDlgPrint  =  CreateDialog  (hlnst,  "PrintDlgBox",  hwnd,  lpfnPrintDlgProc)  ; 
SetDlgltemText  (hDlgPrint,  IDD_FNAME,  szTitleName)  ; 

lpfnAbortProc  =  MakeProcInstance  ((FARPROC)  AbortProc,  hlnst)  ; 

Escape  (pd.hDC,  SETABORTPROC,  0,  (LPSTR)  lpfnAbortProc,  NULL)  ; 

GetWindowText  (hwnd,  szJobName,  sizeof  (szJobName))  ; 


(continued) 
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if  (Escape  (pd.hDC,  STARTDOC,  strlen  (szJobName),  szJobName,  NULL)  0) 

{ 

for  (nColCopy  =  0  ; 

nColCopy  <  (pd. Flags  &  PD_COLLATE  ?  pd.nCopies  :  1)  ; 
nColCopy++) 

{ 

for  (nPage  =  0  ;  nPage  <  nTotal Pages  ;  nPage++) 

{ 

for  (nNonColCopy  =  0  ; 

nNonColCopy  <  (pd. Flags  &  PD_COLLATE  ?  1  :  pd.nCopies)  ; 
nNonColCopy++) 

{ 

for  (nLine  =  0  ;  nLine  <  nLinesPerPage  ;  nLine-H-) 

{ 

nLineNum  =  nLinesPerPage  *  nPage  +  nLine  ; 

if  (nLineNum  >  nTotalLines) 
break  ; 

*  (short  *)  npstrBuffer  =  nCharsPerLine  ; 

TextOut  (pd.hDC,  0,  yChar  *  nLine,  npstrBuffer, 
(short)  SendMessage  (hwndEdit,  EM_GETLINE, 
nLineNum,  (LONG)  ( LPSTR)  npstrBuffer))  ; 

} 

if  (Escape  (pd.hDC,  NEWFRAME,  0,  NULL,  NULL)  <  0) 

{ 

bSuccess  =  FALSE  ; 
break  ; 

} 

if  (bUserAbort) 
break  ; 

} 

if  (IbSuccess  !!  bUserAbort) 
break  ; 

} 

if  (IbSuccess  i !  bUserAbort) 
break  ; 

} 

} 

else 

bSuccess  =  FALSE  ; 
if  (bSuccess) 

Escape  (pd.hDC,  ENDDOC,  0,  NULL,  NULL)  ; 


(continued) 
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if  ( IbUserAbort) 

{ 

EnableWindow  (hwnd,  TRUE)  ; 

DestroyWindow  (hDlgPrint)  ; 

} 

LocalFree  ( ( LOCALHANDLE )  npstrBuffer)  ; 

FreeProcInstance  (1 pfnPri ntDl gProc)  ; 

FreeProcInstance  (lpfnAbortProc)  ; 

DeleteDC  (pd.hDC)  ; 

return  bSuccess  &&  IbUserAbort  ; 

} 

In  keeping  with  the  philosophy  of  making  POPPAD  as  simple  as  possible  by  taking  advan¬ 
tage  of  high-level  Windows  features,  the  POPPRNT.C  file  demonstrates  how  to  use  the 
PrintDlg  function.  This  function  is  included  in  the  common  dialog  box  library  and  uses  a 
structure  of  type  PRINTDLG. 

Normally,  a  Print  option  is  included  on  a  program’s  File  menu.  When  the  user  selects 
the  Print  option,  a  program  can  initialize  the  fields  of  the  PRINTDLG  structure  and  call 
PrintDlg. 

PrintDlg  displays  a  dialog  box  that  allows  the  user  to  select  a  page  range  to  print. 
Thus,  this  dialog  box  is  particularly  suitable  for  programs  such  as  POPPAD  that  can  print 
multipage  documents.  The  dialog  box  also  provides  an  edit  field  to  specify  the  number  of 
copies,  and  a  check-box  labeled  “Collate.”  Collation  affects  the  page-ordering  of  multiple 
copies.  For  example,  if  the  document  is  three  pages  long  and  the  user  requests  that  three 
copies  be  printed,  the  program  can  print  them  in  one  of  two  orders.  Collated  copies  are  in 
the  page  order  1,  2,  3, 1,  2,  3, 1,  2,  3.  Noncollated  copies  are  in  the  order  1, 1, 1,  2,  2,  2,  3,  3,  3. 
It’s  up  to  your  program  to  print  the  copies  in  the  correct  order. 

The  dialog  box  also  allows  the  user  to  select  a  nondefault  printer,  and  it  includes  a 
button  labeled  Setup  that  invokes  a  device  mode  dialog  box.  At  the  very  least,  this  allows 
the  user  to  select  portrait  or  landscape  mode. 

On  return  from  the  PrintDlg  function,  fields  of  the  PRINTDLG  structure  indicate  the 
range  of  pages  to  print  and  whether  multiple  copies  should  be  collated.  The  structure  also 
provides  the  printer  device  context  handle,  ready  to  be  used. 

In  POPPRNT.C,  the  PopPrntPrintFile  function  (which  is  called  from  POPPAD  when 
the  user  selects  the  Print  option  from  the  File  menu)  calls  PrintDlg  and  then  proceeds  to 
print  the  file.  PopPrntPrintFile  then  performs  some  calculations  to  determine  the  number 
of  characters  it  can  fit  on  a  line  and  the  number  of  lines  it  can  fit  on  a  page.  This  process  in¬ 
volves  calls  to  GetDeviceCaps  to  determine  the  resolution  of  the  page  and  to  GetText- 
Metrics  for  the  dimensions  of  a  character. 
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The  program  obtains  the  total  number  of  lines  in  the  document  (the  variable 
nTotalLines)  by  sending  an  EM_GETLINECOUNT  message  to  the  edit  control.  A  buffer  for 
holding  the  contents  of  each  line  is  allocated  from  local  memory.  For  each  line,  the  first 
word  of  this  buffer  is  set  to  the  number  of  characters  in  the  line.  Sending  the  edit  control  an 
EM-GETLINE  message  copies  a  line  into  the  buffer;  the  line  is  then  sent  to  the  printer 
device  context  using  TextOut. 

Notice  that  the  logic  to  print  the  document  includes  two  for  loops  for  the  number  of 
copies.  The  first  uses  a  variable  named  nColCopy  and  takes  effect  when  the  user  has  spe¬ 
cified  collated  copies;  the  second  uses  the  nNonColCopy  variable  and  takes  effect  for  non- 
collated  copies. 

The  program  breaks  from  the  for  loop  incrementing  the  page  number  if  the 
NEWFRAME  Escape  call  returns  an  error  or  if  bUserAbort  is  TRUE.  Although  the 
NEWFRAME  call  will  return  before  GDI  finishes  the  call  if  the  return  value  of  the  abort 
procedure  is  FALSE,  it  doesn’t  return  an  error.  For  this  reason,  bUserAbort  is  tested  ex¬ 
plicitly  before  the  next  page  is  started.  If  no  error  is  reported,  the  ENDDOC  Escape  call 
is  made: 

if  (IbError) 

Escape  (hdcPrn,  ENDDOC,  0,  NULL.  NULL)  ; 

You  might  want  to  experiment  with  POPPAD  by  printing  a  multipage  file.  The  file 
being  printed  first  shows  up  in  the  Print  Manager’s  client  area  after  GDI  has  finished  pro¬ 
cessing  the  first  NEWFRAME  Escape  call.  At  that  time,  the  Print  Manager  starts  sending  the 
file  to  the  printer.  If  you  then  cancel  the  print  job  from  POPPAD,  the  Print  Manager  aborts 
the  printing  also — that’s  a  result  of  returning  FALSE  from  the  abort  procedure.  Once  the 
file  appears  in  the  Print  Manager’s  client  area,  you  can  also  cancel  the  printing  by  selecting 
Terminate  from  the  Queue  menu.  In  that  case,  the  NEWFRAME  Escape  call  in  progress  in 
POPPAD  returns  an  SP-USERABORT  error  (equal  to  -3). 

Programmers  new  to  Windows  often  become  inordinately  obsessed  with  the 
ABORTDOC  Escape  function.  This  function  is  rarely  used  in  printing  that  also  uses  the 
NEWFRAME  Escape  function.  As  you  can  see  in  POPPAD,  a  user  can  cancel  a  print  job  at 
almost  any  time,  either  through  POPPAD’s  printing  dialog  box  or  through  the  Print  Man¬ 
ager.  Neither  requires  that  the  program  use  the  ABORTDOC  Escape  function.  The  only 
time  that  ABORTDOC  would  be  allowed  in  POPPAD  is  between  the  STARTDOC  Escape 
call  and  the  first  NEWFRAME  Escape  call,  but  that  code  goes  so  quickly  that  ABORTDOC 
isn’t  necessary. 

Figure  15-10  shows  the  correct  sequence  of  Escape  calls  for  printing  a  multipage 
document.  The  best  place  to  check  for  a  bUserAbort  value  of  TRUE  is  after  each 
NEWFRAME  Escape  call.  The  ENDDOC  Escape  function  is  used  only  when  the  previous 
Escape  calls  have  proceeded  without  error.  In  fact,  once  you  get  an  error  from  any  Escape 
call,  the  show  is  over,  and  you  can  go  home. 


774 


Chapter  15:  Using  the  Printer 


Figure  15-10.  The  sequence  of  Escape  calls  for  multipage  printing. 
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Handling  Error  Codes 

We  have  been  handling  the  return  value  from  the  Escape  function  in  a  relatively  simple 
manner:  If  Escape  returns  a  negative  value,  then  an  error  has  occurred,  and  the  printing 
operation  is  aborted.  You  can  report  errors  to  the  user  more  precisely  by  checking  the 
Escape  return  value  against  five  identifiers  defined  in  WINDOWS.H.  WINDOWS.H  also 
includes  an  identifier  called  SP_NOTREPORTED,  which  is  equal  to  0x4000.  If  a  bitwise 
AND  of  the  return  value  from  Escape  with  SP-NOTREPORTED  is  0,  then  the  error  has 
already  been  reported  to  the  user.  A  bitwise  OR  of  the  return  value  of  Escape  with 
SP_NOTREPORTED  can  be  compared  with  the  five  error-code  identifiers  to  determine 
whether  the  error  has  been  reported  or  not. 

The  following  function  shows  one  method  of  obtaining  a  text  string  identifying  the 
error.  The  function  returns  NULL  if  no  error  has  occurred  or  if  the  error  has  already  been 
reported  to  the  user: 

char  _GetErrorText  (short  nEscapeReturn ) 

{ 

static  char  _szErrorText  []  =  {  "General  Error", 

"Canceled  from  Program", 

"Canceled  from  Print  Manager", 

"Out  of  disk  space", 

"Out  of  memory  space"  }  ; 


if  (nEscapeReturn  >=  0) 
return  NULL  ; 

if  ((nEscapeReturn  &  SP.NOTREPORTED)  ==  0) 
return  NULL  ; 

return  szErrorText  [-nEscapeReturn]  ; 

} 

The  five  error  codes  (with  some  likely  causes)  are  as  follows: 

■  SP_ERROR  (OxFFFF,  or  -1) — Defined  as  indicating  a  “general  error,”  this 
is  the  only  error  code  that  can  be  returned  from  STARTDOC.  It  can  occur 
if  the  GDI  module  or  the  printer  device  driver  can’t  begin  a  document.  If 
the  Print  Manager  isn’t  loaded,  you  can  also  get  this  error  from 
STARTDOC  if  another  program  is  currently  printing  or  if  the  printer  is  off 
line  or  has  no  paper. 

■  SP-APPABORT  (OxFFFE,  or  -2) — This  code  is  documented  as  indicating 
that  the  program’s  abort  procedure  has  returned  a  FALSE  value.  However, 
this  is  the  case  only  if  the  Print  Manager  isn’t  loaded.  If  the  Print  Manager 
is  loaded  and  if  the  abort  procedure  is  passed  an  nCode  parameter  of  0 
and  then  returns  a  FALSE,  the  NEWFRAME  Escape  call  will  return  a 
positive  value,  not  an  SP_APPABORT  error. 
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■  SP-USER ABORT  (OxFFFD,  or  -3) — This  code  indicates  that  the  user 
canceled  the  printing  job  from  the  Print  Manager. 

■  SP_OUTOFDISK  (OxFFFC,  or  -4) — This  code  indicates  that  no  more  disk 
space  is  available.  You’ll  encounter  this  error  code  if  the  disk  drive 
containing  the  TEMP  subdirectory  can’t  accommodate  any  temporary 
metafiles  or  spooler  files.  If  the  TEMP  subdirectory  has  some  existing 
temporary  spooler  files,  then  the  abort  procedure  is  called  during  a 
NEWFRAME  or  NEXTBAND  Escape  call  with  an  nCode  parameter  of 
SP-OUTOFDISK.  If  the  abort  procedure  then  returns  FALSE,  the  Escape 
call  returns  SP_OUTOFDISK. 

■  SP_OUTOFMEMORY  (OxFFFB,  or  -5) — This  code  indicates  that  insuffi¬ 
cient  memory  is  available  for  printing. 


THE  TECHNIQUE  OF  BANDING 

Banding  is  the  technique  of  defining  a  page  of  graphics  as  a  series  of  separately  con¬ 
structed  rectangles  called  bands.  This  approach  relieves  a  printer  driver  of  the  necessity  of 
constructing  an  entire  bitmapped  page  image  in  memory.  Banding  is  most  important  for 
raster  printers  that  have  no  high-level  page-composition  control,  such  as  dot-matrix  print¬ 
ers  and  some  laser  printers. 

Banding  is  one  of  the  most  misunderstood  aspects  of  programming  for  the  printer  in 
Windows.  Part  of  the  problem  lies  in  the  documentation  for  the  GetDeviceCaps  function. 
The  RC_BANDING  bit  of  the  value  returned  from  GetDeviceCaps  with  the  RASTERCAPS 
index  is  documented  as  “requires  banding  support.”  Programmers  looking  at  this  docu¬ 
mentation  assume  that  their  applications  must  use  banding  with  such  printers.  But  this  isn’t 
so.  Most  of  the  information  available  from  GetDeviceCaps  is  intended  solely  for  the  GDI 
module.  This  information  allows  GDI  to  determine  what  the  device  can  do  by  itself  and 
what  it  needs  help  with.  The  banding  requirement  falls  into  this  category. 

In  general,  an  application  program  doesn’t  need  to  include  its  own  banding  logic.  As 
you’ve  seen,  when  you  make  GDI  calls  that  define  a  page  of  graphics,  the  GDI  module 
stores  these  calls  in  a  metafile  and  then  uses  banding  to  set  a  clipping  region  before  playing 
this  metafile  into  the  printer  device  driver.  This  is  transparent  to  the  application  program. 
Under  certain  conditions,  however,  an  application  might  want  to  take  over  the  respon¬ 
sibility  for  doing  banding.  When  an  application  uses  banding,  the  GDI  module  doesn’t 
create  the  intermediary  metafile.  Instead,  the  drawing  commands  for  each  band  are 
passed  to  the  printer  device  driver.  There  are  two  advantages  to  this  approach: 

■  It  can  increase  printing  speed.  The  application  needs  to  call  only  those 
GDI  functions  that  draw  something  in  each  particular  band,  which  is 
faster  than  having  the  GDI  module  play  the  entire  metafile  into  the  device 
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driver  for  each  band.  Even  if  the  program  simply  draws  the  entire  page  for 
each  band,  the  process  can  still  be  faster  than  having  the  GDI  module 
create  and  read  the  disk-based  metafile,  because  the  program  doesn’t 
have  to  access  a  disk. 

■  It  can  reduce  the  disk  space  normally  required  for  printing.  If  the 
application  is  printing  bitmaps  but  is  not  doing  its  own  banding,  then 
these  bitmaps  must  be  stored  in  the  metafile  that  GDI  creates.  This 
situation  can  result  in  a  metafile  as  large  as  the  printer  output  file  that  the 
GDI  module  eventually  creates. 

■  Banding  is  particularly  important  for  printing  bitmaps,  because  they 
occupy  a  large  amount  of  space  in  the  metafile.  (Printing  a  bitmap 
requires  selecting  the  bitmap  into  a  memory  device  context  and  using 
BitBlt  or  StretchBlt  to  write  it  to  the  printer  device  context.) 

But  banding  also  further  complicates  the  printing  process,  as  you’ll  see  when  we  create 
PRINT4,  the  final  version  of  our  printing  program. 

Strike  Up  the  Bands 

To  have  your  program  do  its  own  banding,  you  first  define  a  variable  of  type  RECT: 

RECT  rect  ; 

You’ll  recall  that  the  RECT  structure  has  four  fields  named  left ,  top ,  right ,  and  bottom.  For 
each  page,  you  start  by  making  an  Escape  call  for  the  subfunction  NEXTBAND,  passing  to 
it  a  pointer  to  rect.  On  return,  rect  contains  the  coordinates  of  the  first  band.  The  coordi¬ 
nates  are  always  device  coordinates  (pixels)  regardless  of  the  current  mapping  mode  of  the 
printer  device  context.  You  make  GDI  calls  to  print  in  that  band.  You  then  call  the  NEXT- 
BAND  Escape  function  again  to  obtain  the  coordinates  of  the  next  band,  and  you  print  in 
that  band.  When  the  RECT  structure  passed  to  Escape  is  returned  empty  (all  fields  set  to  0), 
the  page  is  done. 

Here’s  what  the  code  to  print  a  single  page  looks  like.  For  simplicity’s  sake,  this  code 
doesn’t  take  into  account  errors  that  can  be  returned  from  the  Escape  functions  or  checks 
of  the  bUserAbort  value: 

Escape  (hdcPrn,  NEXTBAND,  0,  NULL,  ( LPSTR)  &rect)  ; 

while  ( ! I sRect Empty  (&rect)) 

{ 

[call  GDI functions  to  print  in  band] 

Escape  (hdcPrn,  NEXTBAND,  0,  NULL,  (LPSTR)  &rect)  ; 

} 

Each  NEXTBAND  Escape  call  (except  the  first)  performs  a  function  similar  to  the 
NEWFRAME  Escape  call:  It  signals  to  the  GDI  module  and  to  the  printer  device  driver  that 
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the  entire  band  has  been  defined  and  that  it  can  now  be  saved  in  a  disk  file  (or  written  to 
the  printer  if  the  Print  Manager  is  not  loaded).  You  don’t  want  to  call  the  NEWFRAME 
Escape  function  after  this  loop  has  run  its  course.  If  you  do  so,  you’ll  get  a  blank  page  be¬ 
tween  each  printed  page.  Nor  can  you  terminate  the  loop  before  receiving  an  empty  rect¬ 
angle  and  then  make  a  NEWFRAME  Escape  call  to  skip  the  rest  of  the  page.  In  short,  you 
use  either  NEWFRAME  to  print  a  page  without  banding  or  multiple  NEXTBAND  calls  to 
print  a  page  with  banding.  Don’t  mix  NEWFRAME  and  NEXTBAND  Escape  functions  for 
the  same  page. 

It’s  easiest  to  visualize  banding  for  a  dot-matrix  printer.  Before  illustrating  the  pro¬ 
cess,  we  need  to  make  a  distinction  between  the  “top  of  the  paper”  (which  is  always  the 
section  of  the  paper  printed  first)  and  the  “top  of  the  page”  (which  depends  on  whether 
the  printer  driver  is  in  portrait  or  landscape  mode). 

In  portrait  mode,  the  top  of  the  page  is  the  same  as  the  top  of  the  paper.  The  bands  go 
down  the  page.  The  rect. left  value  in  the  RECT  structure  set  by  the  NEXTBAND  Escape 
call  is  always  0,  and  rect. right  is  always  equal  to  the  width  of  the  printing  area  in  pixels 
(the  value  obtained  from  GetDeviceCaps  with  a  HORZRES  parameter).  For  the  first  band, 
rect. top  equals  0.  For  each  successive  band,  rect.top  equals  the  rect.  bottom  value  of  the  pre¬ 
vious  band.  For  the  last  band,  rect. bottom  equals  the  height  of  the  printing  area  in  pixels. 
(See  Figure  15-11.) 

rect.left=  0  rect.right=  HORZRES 

0 


rect.top 
rect.  bottom 


VERTRES 

Figure  15-11.  Banding  for  a  dot-matrix  printer  in  portrait  mode. 

Thus  in  each  band,  you  can  print  from  the  rect.left  and  rect.top  coordinates  up  to 
(but  not  including)  the  rect. right  and  rect. bottom  coordinates.  If  you  call  the  function: 

Rectangle  (hdcPrn,  rect.left,  rect.top,  rect. right,  rect. bottom)  ; 


First  band 


Last  band 
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the  rectangle  will  be  printed  on  the  outermost  edges  of  the  band.  (Recall  that  the  right  and 
bottom  sides  of  the  rectangle  drawn  by  Rectangle  are  actually  one  pixel  short  of  the  points 
indicated  by  the  last  two  parameters.) 

In  landscape  mode,  the  dot-matrix  printer  must  print  the  document  sideways,  start¬ 
ing  from  the  left  side  of  the  page.  The  bands  are  in  exactly  the  same  area  on  the  paper,  but 
the  rectangle  coordinates  are  different,  because  the  left  side  of  the  page  is  now  the  top 
of  the  paper.  In  landscape  mode,  rect.top  is  always  0,  and  rect. bottom  is  a  constant  equal 
to  the  height  of  the  printing  area  in  pixels  (the  value  obtained  from  GetDeviceCaps  using 
the  VERTRES  parameter).  For  the  first  band,  rect.left  equals  0.  For  the  last  band,  rect.right 
is  the  width  of  the  printing  area  in  pixels.  (See  Figure  15-12.) 

A  laser  printer  or  a  plotter  might  handle  banding  differently  from  a  dot-matrix  printer, 
because  the  printer  output  might  not  need  to  be  sent  to  the  printer  sequentially  from  the  top 
of  the  page  to  the  bottom.  Although  Figures  15-11  and  15-12  represent  the  normal  case,  your 
program  shouldn’t  assume  that  the  banding  rectangles  will  follow  these  patterns. 


rect.bottom  =  VERTRES  rect.top  =  0 


First  band 

Last  band 

0 


rect.left 

rect.right 


HORZRES 


Figure  15-12.  Banding  for  a  dot-matrix  printer  in  landscape  mode. 

Separating  your  printer  output  into  bands  might  seem  like  a  major  headache.  But 
even  if  you  use  banding,  you  don’t  need  to  include  a  lot  of  banding  logic.  The  band  is  a  clip¬ 
ping  region.  You  can  make  GDI  calls  that  print  outside  the  band,  and  Windows  will  ignore 
everything  except  what  falls  inside  the  band.  This  means  that  for  each  band,  you  can  make 
all  the  GDI  calls  for  the  entire  page. 

You  can  determine  whether  a  particular  driver  requires  banding  support  by  checking 
the  RC_BANDING  bit  of  the  value  returned  from  GetDeviceCaps  using  the  RASTERCAPS 
parameter.  As  I  mentioned  before,  this  information  is  of  concern  only  to  GDI.  Whether  a 
driver  requires  banding  support  or  not,  the  GDI  module  always  supports  the  NEXTBAND 
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Escapee  all.  If  the  driver  doesn’t  require  banding  support,  the  first  NEXTBAND  Escape  call 
for  a  page  returns  a  rectangle  equal  to  the  size  of  the  printing  area.  The  second  NEXT- 
BAND  call  for  a  page  returns  an  empty  rectangle. 

A  Different  Use  of  the  Abort  Procedure 

When  a  program  assumes  responsibility  for  banding,  the  GDI  module  uses  the  abort  pro¬ 
cedure  somewhat  differently  than  it  does  otherwise.  If  the  Print  Manager  isn’t  loaded,  the 
GDI  module  frequently  calls  the  abort  procedure  with  an  nCode  parameter  of  0  while  pro¬ 
cessing  the  NEXTBAND  Escape  call,  just  as  it  does  when  processing  NEWFRAME.  How¬ 
ever,  if  the  Print  Manager  is  loaded  (the  more  normal  case),  the  GDI  module  calls  the  abort 
procedure  only  if  it  runs  out  of  disk  space.  The  nCode  parameter  is  SP-OUTOFDISK. 

This  arrangement  presents  a  problem.  Unless  the  GDI  module  runs  out  of  disk  space, 
the  user  can’t  switch  to  another  program  until  the  application  currently  printing  is  finished. 
Moreover,  although  the  printing  dialog  box  is  displayed,  the  user  can’t  cancel  the  print  job, 
because  the  dialog  box  can’t  get  messages  until  the  abort  procedure  is  called.  The  solution 
to  this  problem  is  fairly  simple.  Your  printing  routine  can  call  the  abort  procedure  itself 
between  the  GDI  drawing  functions  that  make  up  the  page.  Although  the  operation  of 
Windows  isn’t  as  smooth  as  when  the  GDI  module  calls  the  abort  procedure,  this  approach 
at  least  allows  the  user  to  cancel  the  print  job  or  move  on  to  another  task. 

Don’t  call  the  abort  procedure  directly.  Instead,  use  the  pointer  returned  from 
MakeProcInstance.  For  instance,  if  your  abort  procedure  is  called  AbortProc  and  the 
pointer  returned  from  MakeProcInstance  is  called  IpfnAbortProc,  you  can  call  AbortProc 
using: 

IpfnAbortProc  (hdcPrn,  0)  ; 

The  PRINT4  program,  shown  in  Figure  15-13,  adds  banding  to  the  printing  logic  in 
PRINT3.  PRINT4  also  requires  the  PRINT.RC  file  in  Figure  15-8  and — like  all  our  PRINT 
programs — the  PRINT.C  file  in  Figure  15-5. 

PRINT4.MAK 

# . - 

#  PRINT4.MAK  make  file 

# 

print4.exe  :  print. obj  print4.obj  print4.def  print. res 

$(WINLINK)  print4  print,  print4,  NUL,  $(WINLIB),  print4 
rc  -t  print. res  print4.exe 

print. obj  :  print. c 
$ ( WI NCC )  print. c 

Figure  15-13.  The  PRINT4 program.  (continued) 
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print4.obj  :  print4.c 
KWINCC)  print4.c 

print. res  :  print. rc 
$ ( WI NRC )  print. rc 


PRINT4.C 

/* - - - 

PRINT4.C  --  Printing  with  Banding 

(c)  Charles  Petzold,  1992 
. -*/ 


^include  <windows.h> 

HDC  GetPrinterDC  (void)  ;  //  in  PRINT. C 

typedef  BOOL  (FAR  PASCAL  *  ABORTPROC)  (HDC,  short)  ; 

HANDLE  hlnst  ; 

char  szAppName  []  =  "Print4"  ; 

char  szCaption  []  =  "Print  Program  4  (Banding)"  ; 

BOOL  bUserAbort  ; 

HWND  hDlgPrint  ; 

BOOL  FAR  PASCAL  .export  PrintDlgProc  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM_I NITDIALOG  : 

SetWindowText  (hDlg,  szAppName)  ; 

EnableMenuItem  (GetSystemMenu  (hDlg,  FALSE),  SC.CLOSE, 

MF.GRAYED)  ; 

return  TRUE  ; 

case  WM.COMMAND  : 

bUserAbort  =  TRUE  ; 

EnableWindow  (GetParent  (hDlg),  TRUE)  ; 

DestroyWindow  (hDlg)  ; 
hDlgPrint  =  0  ; 
return  TRUE  ; 

} 

return  FALSE  ; 

} 


(continued) 
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BOOL  FAR  PASCAI _ export  AbortProc  (HDC  hdcPrn,  short  nCode) 

{ 

MSG  msg  ; 

while  (IbUserAbort  &&  PeekMessage  (&msg,  NULL,  0,  0,  PM_REM0VE) ) 

{ 

if  (IhDlgPrint  !!  ! IsDi al ogMessage  (hDlgPrint,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  ( &msg )  : 

} 

} 

return  IbUserAbort  ; 

} 


BOOL  PrintMyPage  (HWND  hwnd) 

{ 

static  char  szSpMsg  []  =  "Print4:  Printing"  ; 
static  char  szText  []  =  "Hello  Printer!"  ; 

ABORTPROC  lpfnAbortProc  ; 

BOOL  bError  =  FALSE  ; 

FARPROC  lpfnPrintDlgProc  ; 

HDC  hdcPrn  ; 

RECT  rect  ; 

short  xPage,  yPage  ; 

if  (NULL  ==  (hdcPrn  =  GetPrinterDC  ())) 
return  TRUE  ; 

xPage  =  GetDeviceCaps  (hdcPrn,  HORZRES)  ; 
yPage  =  GetDeviceCaps  (hdcPrn,  VERTRES)  ; 

EnableWindow  (hwnd,  FALSE)  ; 

bUserAbort  =  FALSE  ; 

lpfnPrintDlgProc  =  MakeProcInstance  ((FARPROC)  PrintDlgProc,  hlnst)  ; 
hDlgPrint  =  CreateDialog  (hlnst,  "PrintDlgBox",  hwnd,  lpfnPrintDlgProc)  ; 

lpfnAbortProc  =  (ABORTPROC)  MakeProcInstance  ((FARPROC)  AbortProc,  hlnst)  ; 
Escape  (hdcPrn,  SETABORTPROC,  0.  ( LPSTR)  lpfnAbortProc,  NULL)  ; 


if  (Escape  (hdcPrn,  STARTDOC,  sizeof  szSpMsg  -  1,  szSpMsg,  NULL)  >  0  && 
Escape  (hdcPrn,  NEXTBAND,  0,  NULL,  (LPSTR)  &rect)  >  0) 

{ 

while  UIsRectEmpty  (&rect)  &&  IbUserAbort) 

{ 

lpfnAbortProc  (hdcPrn,  0)  ; 

Rectangle  (hdcPrn,  rect. left,  rect. top,  rect. right, 

rect. bottom)  ; 


lpfnAbortProc  (hdcPrn,  0)  ; 


(continued) 
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MoveTo  (hdcPrn,  0,  0)  ; 

LineTo  (hdcPrn,  xPage,  yPage)  ; 

lpfnAbortProc  (hdcPrn,  0)  ; 

MoveTo  (hdcPrn,  xPage,  0)  ; 

LineTo  (hdcPrn,  0,  yPage)  ; 

SaveDC  (hdcPrn)  ; 

SetMapMode  (hdcPrn,  MM.ISOTROPIC)  ; 

SetWindowExt  (hdcPrn,  1000,  1000)  ; 

SetViewportExt  (hdcPrn,  xPage  /  2,  -yPage  /  2)  ; 
SetViewportOrg  (hdcPrn,  xPage  /  2,  yPage  /  2)  ; 

lpfnAbortProc  (hdcPrn,  0)  ; 

Ellipse  (hdcPrn,  -500,  500,  500,  -500)  ; 

lpfnAbortProc  (hdcPrn,  0)  ; 

SetTextAl ign  (hdcPrn,  TA_BASELINE  !  TA_CENTER)  ; 

TextOut  (hdcPrn,  0,  0,  szText,  sizeof  szText  -  1)  ; 

RestoreDC  (hdcPrn,  -1)  ; 

lpfnAbortProc  (hdcPrn,  0)  ; 

if  (Escape  (hdcPrn,  NEXTBAND,  0,  NULL,  (LPSTR)  &rect)  <  0) 
{ 

bError  =  TRUE  ; 
break  ; 

} 

} 

} 

else 

bError  =  TRUE  ; 

if  ( ! bError ) 

{ 

if  (bUserAbort) 

Escape  (hdcPrn,  ABORTDOC,  0,  NULL,  NULL)  ; 

else 

Escape  (hdcPrn,  ENDDOC,  0,  NULL,  NULL)  ; 

} 

if  ( IbUserAbort) 

{ 


(continued) 
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EnableWindow  (hwnd,  TRUE)  ; 
DestroyWindow  (hDlgPrint)  : 

} 

FreeProcInstance  OpfnPrintDlgProc)  ; 
FreeProcInstance  ( { FARPROC )  lpfnAbortProc)  ; 
DeleteDC  (hdcPrn)  ; 

return  bError  ! :  bUserAbort  ; 

} 


PRINT4.DEF 


;  PRINT4.DEF  module  definition  file 


NAME 


PRINT4 


DESCRIPTION  'Printing  Program  No.  4  (c)  Charles  Petzold,  1992’ 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


PRINT4  differs  from  PRINT3  in  only  a  few  particulars.  In  order  for  A bortProc  to  be  called 
while  the  program  is  printing,  the  GDI  drawing  routines  have  been  moved  into 
PrintMyPage.  You’ll  notice  that  the  Rectangle  function  prints  the  rectangle  for  each  band 
rather  than  a  rectangle  on  the  border  of  the  entire  page.  This  allows  you  to  see  where  the 
bands  are  for  a  particular  printer.  The  structure  of  the  printing  operation  looks  like  this: 

if  (Escape  (hdcPrn,  STARTDOC,  sizeof  szSpMsg  -  1,  szSpMsg,  NULL)  >  0  && 

Escape  (hdcPrn,  NEXTBAND,  0,  NULL,  ( LPSTR)  &rect)  >  0) 

{ 

while  ( ! IsRectEmpty  (&rect)  &&  ! bUserAbort ) 

{ 

[make  GDI  calls  and  call  abort  procedure] 

if  (Escape  (hdcPrn,  NEXTBAND,  0,  NULL,  (LPSTR)  &rect)  <  0) 

{ 

bError  =  TRUE  ; 
break  ; 

} 

} 

} 

else 

bError  =  TRUE  ; 
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The  while  loop  for  the  band  proceeds  only  if  the  rectangle  isn’t  empty  and  if  the  user 
hasn’t  canceled  the  print  job  from  the  dialog  box.  PRINT4  has  to  check  the  return  value 
from  each  NEXTBAND  Escape  call  and  set  bErrori f  Escape  returns  a  negative  value.  If  no 
Escape  call  returns  an  error,  then  the  print  job  must  either  be  ended  with  the  ENDDOC 
Escape  call  or  be  aborted  with  the  ABORTDOC  Escape  call.  If  the  user  cancels  printing 
during  the  NEXTBAND  loop,  then  the  print  job  must  be  aborted  using  the  ABORTDOC 
call.  The  code  to  do  this  is  as  follows: 

if  ( IbError) 

{ 

if  (bUserAbort) 

Escape  (hdcPrn,  ABORTDOC,  0,  NULL,  NULL)  ; 

el  se 

Escape  (hdcPrn,  ENDDOC,  0,  NULL,  NULL)  ; 

} 

THE  PRINTER  AND  FONTS 

Chapter  14  includes  a  program  called  JUSTIFY  that  uses  GDI-based  fonts  to  display  format¬ 
ted  text.  Programs  that  work  with  formatted  text  on  the  screen  usually  also  need  to  print 
this  text.  In  fact,  word-processing  and  desktop  publishing  programs  generally  use  the  dis¬ 
play  solely  to  provide  a  preview  of  the  printed  output. 

TrueType  provides  the  easiest  route  to  accurately  rendering  text  on  the  screen  as  it 
will  appear  when  printed.  One  approach  you  can  use  is  to  restrict  your  program  to  using 
only  TrueType  fonts.  If  you  enumerate  fonts  using  the  EnumFonts  function  (as  demon¬ 
strated  in  the  FONTLIST  program  in  Chapter  14),  you  can  check  the  TRUETYPE-FONT- 
TYPE  bit  of  the  nFontType  parameter  to  the  call-back  function.  You  then  use  a  listbox  to 
display  only  those  fonts  with  the  TRUETYPE-FONTTYPE  bit  set. 

If  you  let  the  user  choose  a  font  by  displaying  the  dialog  box  provided  by  the  Choose- 
Font  function  in  the  common  dialog  box  library  (as  demonstrated  in  the  JUSTIFY  program 
in  Chapter  14),  you  can  include  the  CF-TTONLY  flag  in  the  Flags  field  of  the  CHOOSE- 
FONT  structure  to  restrict  the  list  to  TrueType  fonts. 

However,  restricting  font  selection  to  TrueType  may  disturb  those  users  who  have  in¬ 
vested  money  in  downloadable  fonts  or  font  cartridges  for  their  laser  printers.  These  printer 
fonts  will  not  be  listed  for  selection  by  the  user.  To  display  printer  fonts  in  the  dialog  box 
created  by  ChooseFont,  you  should  include  the  CF-PRINTERFONTS  constant  in  the  Flags 
field  of  the  CHOOSEFONT  structure. 

You  must  also  set  the  hDC  field  of  the  CHOOSEFONT  structure  to  the  device  context 
handle  for  the  printer.  The  fonts  displayed  in  the  list  box  will  then  be  limited  to  the  internal 
printer  fonts,  TrueType  fonts,  and  stroke  fonts.  (To  eliminate  the  stroke  fonts  from  the 
listbox,  also  use  the  flag  CF-NOVECTORFONTS.) 
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If  you  let  the  user  choose  printer  fonts,  what  you  show  on  the  display  can  only  ap¬ 
proximate  what  the  printer  will  print.  If  the  printer  offers  a  15-point  Zapf  Chancery  font,  for 
example,  it  can  be  approximated  with  a  15-point  TrueType  font,  but  the  character  widths  of 
the  TrueType  font  will  not  be  the  same  as  the  Zapf  Chancery  font.  Even  for  TrueType  fonts, 
there  may  be  rounding  errors  in  character  widths  that  cause  differences  between  the 
screen  display  and  the  printer. 

In  short,  if  you’re  writing  a  program  that  must  display  formatted  text  destined  for  a 
printer,  you  can  count  on  some  work  ahead.  Here  are  some  guidelines  to  get  you  started. 

When  you  display  formatted  text  on  the  screen,  you  want  tot  space  the  text  based  on 
how  it  will  be  eventually  printed.  You  can  use  GetDeviceCaps  and  the  GETPHYSPAGESIZE 
Escape  call  to  determine  the  size  of  the  paper  and  the  size  of  the  printable  area.  For  in¬ 
stance,  if  the  paper  is  8V2  inches  wide  and  the  user  selects  left  and  right  margins  of  1  inch, 
then  you  want  to  display  text  on  the  screen  using  a  width  of  6Y2  inches.  The  “logical  twips” 
mapping  mode  discussed  in  Chapter  14  is  appropriate  for  this  display.  There’s  a  catch,  how¬ 
ever.  If  the  user  selects  a  15-point  font  that  the  printer  supports,  you’ll  have  to  approximate 
that  font  on  the  display  with  a  14-point  font — but  you  can’t  use  this  14-point  display  font  to 
determine  the  amount  of  15-point  text  that  can  fit  in  one  printed  line.  You  must  determine 
this  instead  based  on  the  printer  font.  Likewise,  you  must  use  the  printer  font  to  deter¬ 
mine  how  many  lines  fit  on  a  page. 

To  format  the  display  text,  you’ll  need  both  a  handle  to  the  screen  device  context  (to 
display  the  text  on  the  screen)  and  a  handle  to  a  printer  information  context.  You  don’t 
need  a  printer  device  context  handle  until  you  actually  want  to  print.  Follow  these  steps: 

1.  Put  together  a  logical  font  structure  with  the  typeface  name,  the  type  size, 
and  the  attributes  selected  by  the  user,  and  select  that  logical  font  into  the 
printer  information  context. 

2.  Call  GetText Metrics  for  the  printer  information  context  to  determine  the 
real  size  and  characteristics  of  the  selected  printer  font.  Call  GetTextFace 
to  obtain  the  typeface  name. 

3.  Use  the  information  obtained  in  Step  2  to  create  another  logical  font 
structure  based  on  the  size  and  characteristics  of  the  printer  font,  and 
select  this  logical  font  into  the  screen  device  context.  The  font  now  se¬ 
lected  into  the  screen  device  context  closely  approximates  the  font 
selected  into  the  printer  information  context. 

4.  When  you  write  the  text  to  the  display,  follow  the  general  procedure  used 
in  the  Justify  function  of  the  JUSTIFY  program.  However,  go  through  the 
GetTextExtent  and  SetTextJustification  logic  using  the  printer  information 
context,  but  stop  short  of  TextOut.  This  approach  allows  you  to  determine 
the  amount  of  text  that  fits  in  each  line  and  the  number  of  lines  that  fit  on 
a  page. 
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5.  When  you  have  established  each  line  of  text  as  appropriate  for  the  printer, 
you  can  call  GetTextExtent  and  (possibly)  SetTextJustification  using  the 
screen  display  context.  You  then  call  TextOut  to  display  the  line. 

To  print  the  text,  you’ll  probably  use  code  structured  like  that  in  the  POPPRNT.C  file 
combined  with  the  logic  in  the  Justify  function  of  JUSTIFY.C.  You  obtain  a  printer  device 
context  and  go  through  the  GetTextExtent  and  SetTextJustification  logic  again,  this  time 
using  TextOut  to  print  each  line. 
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CHAPTER  16 


The 

Clipboard 


The  Windows  clipboard  allows  data  to  be  transferred  from  one  program  to  another.  It  is  a 
relatively  simple  mechanism  that  doesn’t  require  much  overhead  in  either  the  program  that 
places  data  in  the  clipboard  or  the  program  that  later  gets  access  to  it. 

Let’s  clear  up  one  possible  point  of  confusion  right  away:  The  CLIPBOARD  program 
that  comes  with  Windows  is  not  the  clipboard.  It  is  instead  a  “clipboard  viewer”  that  dis¬ 
plays  the  current  contents  of  the  clipboard.  (We’ll  write  our  own  simple  clipboard  viewer 
later  in  this  chapter.)  The  clipboard  is  simply  a  series  of  functions  in  Windows’  USER  mod¬ 
ule  that  facilitate  the  exchange  of  memory  blocks  between  programs. 

Many  programs  that  deal  with  documents  or  other  data  include  an  Edit  menu  with 
the  options  Cut,  Copy,  and  Paste.  When  a  user  selects  Cut  or  Copy,  the  program  transfers 
data  from  the  program  to  the  clipboard.  This  data  is  in  a  particular  format,  such  as  text,  a 
bitmap,  or  a  metafile.  When  a  user  selects  Paste  from  the  menu,  the  program  determines  if 
the  clipboard  contains  data  in  a  format  that  the  program  can  use  and,  if  so,  transfers  data 
from  the  clipboard  to  the  program. 

Programs  should  not  transfer  data  into  or  out  of  the  clipboard  without  an  explicit 
instruction  from  the  user.  For  example,  a  user  who  performs  a  Cut  or  a  Copy  operation  in 
one  program  should  be  able  to  assume  that  the  data  will  remain  in  the  clipboard  until  the 
next  Cut  or  Copy  operation  or  until  the  user  employs  a  program — such  as  the  BLOWUP2 
program  presented  in  this  chapter — specifically  designed  to  manipulate  the  clipboard. 
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SIMPLE  USE  OF  THE  CLIPBOARD 

We’ll  begin  by  looking  at  the  code  involved  for  transferring  data  to  the  clipboard  (Cut  and 

Copy)  and  getting  access  to  clipboard  data  (Paste). 

The  Standard  Clipboard  Data  Formats 

Windows  supports  various  standard  clipboard  formats  that  have  WINDOWS. H  identifiers. 

These  are: 

■  CF_TEXT — a  NULL-terminated  ANSI  character-set  character  string 
containing  a  carriage  return  and  a  linefeed  character  at  the  end  of  each 
line.  This  is  the  simplest  form  of  clipboard  data.  The  data  to  be 
transferred  to  the  clipboard  is  stored  in  a  global  memory  block  and  is 
transferred  using  the  handle  to  the  block.  The  memory  block  becomes  the 
property  of  the  clipboard,  and  the  program  that  creates  the  block  should 
not  continue  to  use  it. 

■  CF_BITMAP — a  device-dependent  bitmap.  The  bitmap  is  transferred  to 
the  clipboard  using  the  bitmap  handle.  Again,  a  program  should  not 
continue  to  use  this  bitmap  after  giving  it  to  the  clipboard. 

■  CF_METAFILEPICT — a  “metafile  picture.”  This  isn’t  exactly  the  same  as  a 
metafile  (described  in  Chapter  13).  Rather,  it’s  a  metafile  with  some 
additional  information  in  the  form  of  a  small  structure  of  type 
METAFILEPICT.  A  program  transfers  a  metafile  picture  to  the  clipboard 
using  the  handle  to  a  global  memory  block  containing  this  structure.  The 
four  fields  of  the  METAFILEPICT  structure  are  mm  (int),  the  mapping 
mode  for  the  metafile;  xExt  (int)  and  yExt  (int),  in  simple  terms,  the  width 
and  height  of  the  metafile  image;  and  hMF  (HANDLE),  the  handle  to  the 
metafile.  (I’ll  discuss  the  xExt  and  yExt  fields  in  detail  later  in  this 
chapter.)  After  a  program  transfers  a  metafile  picture  to  the  clipboard,  it 
should  not  continue  to  use  either  the  global  memory  block  containing  the 
METAFILEPICT  structure  or  the  metafile  handle,  because  both  will  be 
under  the  control  of  the  USER  module. 

■  CF_SYLK — a  global  memory  block  containing  data  in  the  Microsoft 
“Symbolic  Link”  format.  This  format  is  used  for  exchanging  data  between 
Microsoft  Corporation’s  Multiplan,  Chart,  and  Excel  programs.  It  is  an 
ASCII  format  with  each  line  terminated  with  a  carriage  return  and  a 
linefeed. 

■  CF_DIF — a  global  memory  block  containing  data  in  the  Data  Interchange 
Format  (DIF).  This  is  a  format  devised  by  Software  Arts  for  use  in 
transferring  data  to  the  VisiCalc  spreadsheet  program.  The  format  is  now 
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under  the  control  of  Lotus  Corporation.  This  is  also  an  ASCII  format  with 
lines  terminated  by  carriage  returns  and  linefeeds. 

The  CF-SYLK  and  CF_DIF  formats  are  conceptually  similar  to  the  CF-TEXT  format.  How¬ 
ever,  character  strings  containing  SYLK  or  DIF  data  are  not  necessarily  NULL-terminated, 
because  the  formats  define  the  end  of  the  data.  (For  descriptions  of  these  two  formats,  see 
Jeff  Walden,  File  Formats  for  Popular  PC  Software,  John  Wiley  &  Sons,  1986.) 

■  CF-TIFF — a  global  memory  block  containing  data  in  the  Tag  Image  File 
Format  (TIFF).  This  is  a  format  devised  by  Microsoft,  Aldus  Corporation, 
and  Hewlett-Packard  Company  in  conjunction  with  some  hardware 
manufacturers.  The  format  (which  describes  bitmapped  data)  is  available 
from  Hewlett-Packard. 

■  CF-OEMTEXT — a  global  memory  block  containing  text  data  (similar  to 
CF-TEXT)  but  using  the  OEM  character  set. 

■  CF-DIB — a  global  memory  block  defining  a  device-independent  bitmap. 

The  global  memory  block  begins  with  a  BITMAPINFO  structure  followed 
by  the  bitmap  bits. 

■  CF-PALETTE — a  handle  to  a  color  palette.  This  is  generally  used  in 
conjunction  with  CF-DIB  for  defining  a  color  palette  used  by  the  bitmap. 

Transferring  Text  to  the  Clipboard 

Let’s  assume  that  you  want  to  transfer  a  character  string  to  the  clipboard  and  that  you  have  a 
pointer  (called  pString )  to  this  string.  This  can  be  a  near  pointer  if  the  text  is  stored  in  your 
program’s  local  data  segment  or  a  far  pointer  if  the  text  is  stored  in  a  global  data  segment. 
You  want  to  transfer  wLength  bytes  of  this  string. 

First,  allocate  a  moveable  global  memory  block  of  wLength  size.  Include  room  for  a 
terminating  NULL: 

hGlobal Memory  =  GlobalAlloc  (GHND,  (DWORD)  wLength  +  1)  ; 

The  value  of  hGlobalMemory  will  be  NULL  if  the  block  could  not  be  allocated.  If  the  allo¬ 
cation  is  successful,  lock  the  block  to  get  a  far  pointer  to  it: 

lpGlobal Memory  =  GlobalLock  (hGlobalMemory)  ; 

Copy  the  character  string  into  the  global  memory  block: 

for  (n  =  0  ;  n  <  wLength  ;  n++) 

*lpGlobalMemory++  =  *pString++  ; 

You  don’t  need  to  add  the  terminating  NULL  because  the  GHND  flag  for  GlobalAlloc  zeroes 
out  the  entire  memory  block  during  allocation.  Unlock  the  block: 

GlobalUnlock  (hGlobalMemory)  ; 
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Now  you  have  a  global  memory  handle  that  references  a  memory  block  containing 
the  NULL-terminated  text.  To  get  this  into  the  clipboard,  open  the  clipboard  and  empty  it: 

OpenCl i pboa rd  (hwnd)  ; 

EmptyCl i pboard  0  ; 

Give  the  clipboard  the  global  memory  handle  using  the  CF_TEXT  identifier,  and  close  the 
clipboard: 

SetCl i pboa rdData  (CF_TEXT,  hGl obalMemory)  ; 

CloseClipboard  0  ; 

You’re  done. 

Here  are  some  rules  concerning  this  process: 

■  Call  OpenClipboard  and  CloseClipboard  while  processing  a  single  mes¬ 
sage.  Don’t  leave  the  clipboard  open  when  you  exit  the  window  proce¬ 
dure.  Don’t  let  control  transfer  to  another  program  (perhaps  by  calling 
SendMessage  or  PeekMessage )  while  the  clipboard  is  open. 

■  Don’t  give  the  clipboard  a  locked  memory  handle. 

■  After  you  call  SetClipboardData ,  don’t  continue  to  use  the  global  memory 
block.  It  no  longer  belongs  to  your  program,  and  you  should  treat  the 
handle  as  invalid.  If  you  need  to  continue  to  access  the  data,  make  another 
copy  of  it  or  read  it  from  the  clipboard  (as  described  in  the  next  section). 

You  can  also  continue  to  reference  the  block  between  the  SetClip¬ 
boardData  call  and  the  CloseClipboard  call,  but  you  must  use  the  glo¬ 
bal  handle  that  is  returned  from  SetClipboardData.  Unlock  this  handle 
before  you  call  CloseClipboard. 

Getting  Text  from  the  Clipboard 

Getting  text  from  the  clipboard  is  only  a  little  more  complex  than  transferring  text  to  the 
clipboard.  You  must  first  determine  whether  the  clipboard  does  in  fact  contain  data  in  the 
CF-TEXT  format.  One  of  the  easiest  methods  is  to  use  the  call: 

bAvailable  =  IsClipboardFormatAvailable  (CF_TEXT)  ; 

This  function  returns  TRUE  (nonzero)  if  the  clipboard  contains  CF-TEXT  data.  We  used 
this  function  in  the  POPPAD2  program  in  Chapter  9  to  determine  whether  the  Paste  item 
on  the  Edit  menu  should  be  enabled  or  grayed.  IsClipboardFormatAvailable  is  one  of  the 
few  clipboard  functions  that  you  can  use  without  first  opening  the  clipboard.  However, 
if  you  later  open  the  clipboard  to  get  this  text,  you  should  also  check  again  (using  the 
same  function  or  one  of  the  other  methods)  to  determine  if  the  CF_TEXT  data  is  still  in 
the  clipboard. 
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To  transfer  the  text  out,  first  open  the  clipboard: 

OpenClipboard  (hwnd)  ; 

Obtain  the  handle  to  the  global  memory  block  referencing  the  text: 
hClipMemory  =  GetCl i pboardData  ( C F_T EXT)  ; 

This  handle  will  be  NULL  if  the  clipboard  doesn’t  contain  data  in  the  CF_TEXT  format. 
This  is  another  way  to  determine  if  the  clipboard  contains  text.  If  GetClipboardData 
returns  NULL,  close  the  clipboard  without  doing  anything  else. 

The  handle  you  receive  from  GetClipboardData  doesn’t  belong  to  your  program — it 
belongs  to  the  clipboard.  The  handle  is  valid  only  between  the  GetClipboardData  and 
CloseClipboard  calls.  You  can’t  free  that  handle  or  alter  the  data  it  references.  If  you  need 
to  have  continued  access  to  the  data,  you  should  make  a  copy  of  the  memory  block. 

Here’s  one  method  for  copying  the  data  into  a  global  memory  segment  that  belongs  to 
your  program.  First,  allocate  a  global  memory  block  of  the  same  size  as  that  referenced 
by  hClipMemory : 

hMyMemory  =  GlobalAlloc  (GHND,  GlobalSize  (hClipMemory))  ; 

Check  for  a  NULL  value  from  GlobalAlloc  to  determine  if  the  block  was  really  allocated.  If 
it  was  allocated,  lock  both  handles  and  get  pointers  to  the  beginning  of  the  blocks: 

lpClipMemory  =  G1 oba 1  Lock  (hClipMemory)  ; 
lpMyMemory  =  Global  Lock  (hMyMemory)  ; 

Because  the  character  string  is  NULL-terminated,  you  can  transfer  the  data  using  Windows’ 
Istrcpy  function: 

lstrcpy  (lpMyMemory,  lpClipMemory)  ; 

Or  you  can  use  some  simple  C  code: 

while  (*lpMyMemory++  =  *1  pCl i pMemory-H-)  ; 

Unlock  both  blocks: 

G1 obal Unlock  (hClipMemory)  ; 

G1 obal Unlock  (hMyMemory)  ; 

Finally,  close  the  clipboard: 

CloseClipboard  0  ; 

Now  you  have  a  global  handle  called  hMyMemory  that  you  can  later  lock  to  access  this  data. 

What  the  Clipboard  Does 

The  clipboard  works  primarily  by  altering  the  memory  allocation  flags  of  global  memory 
blocks.  When  a  program  allocates  a  global  memory  block  using  the  GHND  flag  (a  combi¬ 
nation  of  the  GMEM _MOVE ABLE  and  GMEM_ZEROINIT  flags),  the  memory  block  is 
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marked  as  belonging  to  the  program  (more  precisely,  the  particular  instance  of  the  pro¬ 
gram).  Normally,  Windows  deletes  this  memory  block  when  the  instance  terminates. 
When  a  program  uses  SetClipboardData  to  give  the  global  handle  to  the  clipboard,  Win¬ 
dows  must  transfer  ownership  of  the  memory  block  from  the  program  to  itself.  This  action 
requires  that  Windows  modify  the  memory  allocation  flags  of  the  global  memory  block  by 
calling: 

Global ReAlloc  (hMem,  0L,  GMEM.MODIFY  !  GMEM.SHARE)  ; 

The  USER  module  establishes  ownership  of  the  memory  block.  After  the  SetClip¬ 
boardData  call,  the  global  memory  handle  no  longer  belongs  to  the  program  that  allocated 
it,  and  the  block  won’t  be  freed  when  the  program  terminates.  The  program  that  created 
the  memory  block  can’t  continue  to  use  it  except  when  the  clipboard  gives  the  program 
access  to  the  block.  Now  the  USER  module  must  explicitly  free  the  memory  block,  which  it 
does  when  a  program  calls  Empty  Clipboard. 

When  a  program  calls  GetClipboardData,  Windows  gives  the  program  making  the 
call  the  handle  to  the  global  memory  block  and  allows  the  program  temporary  access  to  the 
memory  block.  The  program  can  then  copy  this  data  into  another  global  memory  block  or 
a  local  memory  block.  Thus,  the  clipboard  is  really  just  a  manager  of  shared  memory  seg¬ 
ments.  One  program  gives  the  clipboard  a  block  of  global  memory.  Other  programs  can 
get  access  to  the  block.  The  clipboard  retains  ownership  of  it. 

Opening  and  Closing  the  Clipboard 

Only  one  program  can  have  the  clipboard  open  at  any  time.  The  purpose  of  the  OpenClip- 
board  call  is  to  prevent  the  clipboard  contents  from  changing  while  a  program  is  using  the 
clipboard.  OpenClipboard  returns  a  BOOL  value  indicating  whether  the  clipboard  was 
successfully  opened.  It  will  not  be  opened  if  another  application  failed  to  close  it.  During 
the  early  stages  of  programming  for  the  clipboard,  you  should  probably  check  this  value, 
but  the  check  isn’t  crucial  in  a  nonpreemptive  multitasking  environment.  If  every  program 
politely  opens  and  then  closes  the  clipboard  during  a  single  message  without  giving  con¬ 
trol  to  other  programs,  then  you’ll  never  run  into  the  problem  of  being  unable  to  open  the 
clipboard. 

I’ve  already  mentioned  avoiding  the  use  of  SendMessage  or  PeekMessage  while  the 
clipboard  is  open,  but  watch  out  for  a  more  subtle  problem  involving  message  boxes:  If  you 
can’t  allocate  a  global  memory  segment  to  copy  the  contents  of  the  clipboard,  then  you 
might  want  to  display  a  message  box.  If  this  message  box  isn’t  system  modal,  however, 
the  user  can  switch  to  another  application  while  the  message  box  is  displayed.  You  should 
either  make  the  message  box  system  modal  or  close  the  clipboard  before  you  display  the 
message  box. 

You  can  also  run  into  problems  if  you  leave  the  clipboard  open  while  you  display  a 
dialog  box.  Edit  fields  in  a  dialog  box  use  the  clipboard  for  cutting  and  pasting  text. 
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Using  the  Clipboard  with  Bitmaps 

In  using  the  CF_BITMAP  format,  you  give  the  clipboard  a  handle  to  a  device-dependent 
bitmap  when  calling  SetClipboardData.  The  GetClipboardData  function  returns  a  handle 
to  a  device-dependent  bitmap. 

You  may  recall  the  BLOWUP1  program  from  Chapter  4,  which  allowed  you  to  block 
out  any  part  of  the  display  and  copy  it  to  BLOWUPl’s  client  area.  BLOWUP1  used  StretchBlt 
to  expand  or  compress  the  size  of  the  blocked-out  area  so  that  it  exactly  fit  the  client  area. 
The  program  had  a  problem,  however:  If  part  of  BLOWUPl’s  client  area  was  destroyed 
(perhaps  by  an  overlapping  window  from  another  program),  BLOWUP1  couldn’t  re-create 
it.  We  could  have  solved  that  problem  by  creating  a  bitmap  based  on  the  size  of  the  area 
BLOWUP1  was  copying.  When  BLOWUP1  needed  to  redisplay  the  bitmap  in  its  client  area, 
it  could  have  selected  the  bitmap  into  a  memory  device  context  and  used  StretchBlt  to  copy 
it  to  the  client  area. 

Let’s  go  one  step  further  and  write  a  revised  version  of  this  program  that  uses  the 
clipboard  to  hold  on  to  this  bitmap.  This  approach  provides  two  advantages: 

■  Any  part  of  the  display  can  now  be  copied  in  bitmap  format  and  stored  in 
the  clipboard. 

■  Any  bitmap  that  is  stored  in  the  clipboard  can  be  copied  into  and  scaled  to 
the  size  of  the  program’s  client  area.  You  can  then  block  out  all  or  part  of 
this  display  and  copy  that  to  the  clipboard.  This  provides  an  easy  manual 
approach  to  scaling  or  cropping  bitmaps. 

The  Revised  BLOWUP  Program 

The  BLOWUP2  program  is  shown  in  Figure  16-1.  You  use  it  the  same  way  as  the  BLOWUP1 
program.  First,  click  the  mouse  in  BLOWUP2’s  client  area.  The  cursor  changes  to  a  cross 
hair.  Now  place  the  cursor  on  one  corner  of  the  rectangle  you  want  to  capture,  press  the 
mouse  button,  drag  the  mouse  to  the  opposite  corner,  and  release  the  button. 

BLOWUP2.MAK 

# 

#  BL0WUP2.MAK  make  file 

#  . . 

blowup2.exe  :  blowup2.obj  blowup2.def 

$(WINLINK)  blowup2,  blowup2,  NUL,  $(WINLIB),  blowup2 
rc  -t  blowup2.exe 

blowup2.obj  :  blowup2.c 
KWINCC)  blowup2.c 

Figure  16-1.  The  BLOWUP2 program. 
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BLOWUP2.C 

/*- . - . - . - - - 

BL0WUP2.C  --  Capture  Screen  Image  to  Clipboard 
(c)  Charles  Petzold,  1992 

- - */ 


#include  <windows.h> 
#include  <stdlib.h> 
typedef  unsigned  int  UINT  ; 


long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "Blowup2"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbr Background 
wndclass. IpszMenuName 
wndclass. 1 pszCl assName 


=  CS.HREDRAW  !  CS.VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL,  IDC.ARR0W)  ; 
=  GetStockObject  (WHITE.BRUSH)  ; 
=  NULL  ; 

=  szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  szAppName, 

WS_0V  ERLAPPEDW I NDOW , 
CW.USEDEFAULT,  CW.USEDEFAULT, 
CW.USEDEFAULT,  CW.USEDEFAULT, 
NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 


(continued) 
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DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  InvertBlock  (HWND  hwnd.  POINT  org,  POINT  len) 

{ 

HDC  hdc  ; 

hdc  =  CreateDC  ("DISPLAY",  NULL,  NULL,  NULL)  ; 

ClientToScreen  (hwnd,  &org)  ; 

PatBlt  (hdc,  org.x,  org.y,  len.x,  len.y,  DSTINVERT)  ; 

DeleteDC  (hdc)  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  BOOL  bCapturing,  bBlocking  ; 

static  POINT  org,  len  ; 

static  short  cxClient,  cyClient  ; 

BITMAP  bm  ; 

HDC  hdc,  hdcMem  ; 

HBITMAP  hBitmap  ; 

PAINTSTRUCT  ps  ; 

switch  (message) 

{ 

case  WM.SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HIWORD  (IParam)  ; 
return  0  ; 

case  WM.LBUTTONDOWN  : 
if  ( ! bCapturi ng ) 

{ 

bCapturing  =  TRUE  ; 

SetCapture  (hwnd)  ; 

SetCursor  (LoadCursor  (NULL,  IDC.CROSS))  ; 

} 

else  if  ( JbBlocking) 

{ 

bBlocking  =  TRUE  ; 

org  =  MAKEPOINT  (IParam)  ; 

} 

return  0  ; 

case  WM.MOUSEMOVE  : 
if  (bCapturing) 

SetCursor  (LoadCursor  (NULL,  IDC.CROSS))  ; 


(continued) 
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if  (bBlocking) 

{ 

len  =  MAKEPOINT  (IParam)  ; 
len.x  -=  org.x  ; 
len.y  -=  org.y  ; 

InvertBlock  (hwnd,  org,  len)  ; 

InvertBlock  (hwnd,  org,  len)  ; 

} 

return  0  ; 

case  WM_LBUTTONUP  : 
if  ( IbBlocking) 
break  ; 

bCapturing  =  bBlocking  =  FALSE  ; 

SetCursor  (LoadCursor  (NULL,  IDC_ARR0W) )  ; 

ReleaseCapture  0  ; 

if  (len.x  ==  0  ; ;  len.y  ==  0) 
break  ; 

hdc  =  GetDC  (hwnd)  ; 

hdcMem  =  CreateCompatibleDC  (hdc)  ; 

hBitmap  =  CreateCompatibleBitmap  (hdc, 

abs  (len.x),  abs  (len.y))  ; 

if  (hBitmap) 

{ 

SelectObject  (hdcMem,  hBitmap)  ; 

StretchBlt  (hdcMem,  0,  0,  abs  (len.x),  abs  (len.y), 
hdc,  org.x,  org.y,  len.x,  len.y,  SRCCOPY)  ; 

OpenClipboard  (hwnd)  ; 

EmptyClipboard  0  ; 

SetCl i pboardData  (CF_BITMAP,  hBitmap)  ; 

Cl oseCl i pboard  ()  ; 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 

} 

else 

MessageBeep  (0)  ; 

DeleteDC  (hdcMem)  ; 

ReleaseDC  (hwnd,  hdc)  ; 
return  0  ; 

case  WM_PAI NT  : 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
hdc  =  BeginPaint  (hwnd,  &ps)  ; 

OpenClipboard  (hwnd)  ; 


(continued) 
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hBitmap  =  GetCl i pboardData  (CF.BITMAP)  ; 

if  (hBitmap  !=  NULL) 

{ 

SetCursor  (LoadCursor  (NULL,  IDC_WAIT) )  ; 

hdcMem  =  CreateCompatibleDC  (hdc)  ; 

SelectObject  (hdcMem,  hBitmap)  ; 

GetObject  (hBitmap,  sizeof  (BITMAP),  ( LPSTR)  &bm)  ; 

SetStretchBl tMode  (hdc,  C0L0R0NC0L0R)  ; 

StretchBlt  (hdc,  0,  0,  cxClient,  cyClient, 

hdcMem,  0,  0,  bm.bmWidth,  bm.bmHeight, 
SRCCOPY)  ; 

SetCursor  (LoadCursor  (NULL.  IDC_ARR0W) )  ; 

DeleteDC  (hdcMem)  ; 

} 

CloseClipboard  0  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


BLOWUP2.DEF 


BL0WUP2.DEF  module  definition  file 


NAME  BL0WUP2 


DESCRIPTION  'Capture  Screen  Image  to  Clipboard  (c)  Charles  Petzold,  1992' 
EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


»$ 
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In  the  earlier  BLOWUP1  program,  the  blocked-out  section  of  the  display  was  copied  to 
BLOWUPl’s  client  area.  In  the  new  version,  the  area  of  the  display  is  copied  to  a  bitmap  in 
a  memory  device  context,  and  the  bitmap  is  transferred  to  the  clipboard. 

When  you’re  blocking  out  an  area  of  the  display  with  the  mouse,  BLOWUP2  retains 
two  structures  of  type  POINT  with  the  initial  corner  (org,  for  “origin”)  and  the  width  and 
height  of  the  rectangle  ( len ,  for  “length”).  If  the  org  point  isn’t  the  upper  left  corner  of  the 
rectangle,  then  one  or  both  of  the  values  in  len  will  be  negative.  When  the  mouse  button  is 
released  (signaling  to  the  program  that  the  user  has  finished  blocking  out  the  rectangle), 
BLOWUP2  creates  a  memory  device  context  and  a  bitmap  using  the  absolute  values  of  the 
lengths  in  the  len  point  structure: 

hdc  =  GetDC  (hwnd)  ; 

hdcMem  =  CreateCompatibl eDC  (hdc)  ; 

hBitmap  =  CreateCompati bl eBi tmap  (hdc,  abs  (len.x),  abs  (len.y))  ; 

If  BLOWUP2  succeeds  in  creating  this  bitmap,  the  program  selects  the  bitmap  into 
the  memory  device  context  and  uses  StretchBlt  to  copy  the  blocked-out  area  of  the  display: 

if  (hBitmap) 

{ 

SelectObject  (hdcMem,  hBitmap)  ; 

StretchBlt  (hdcMem,  0,  0,  abs  (len.x),  abs  (len.y), 
hdc,  org.x,  org.y,  len.x,  len.y,  SRCCOPY)  ; 

Although  we’re  using  StretchBlt  here,  the  image  is  not  being  stretched  or  compressed. 
However,  if  you  block  out  the  rectangle  from  right  to  left,  then  StretchBlt  is  needed  to  flip 
the  image  around  a  vertical  axis.  Similarly,  if  you  block  it  out  from  bottom  to  top,  then 
StretchBlt  turns  it  upside  down. 

The  program  then  opens  and  empties  the  clipboard,  transfers  the  bitmap  to  the  clip¬ 
board,  and  closes  the  clipboard: 

OpenClipboard  (hwnd)  ; 

EmptyCl i pboa  rd  ()  ; 

SetCl ipboardData  ( C F_B I TMAP ,  hBitmap)  ; 

Cl oseCl i pboa  rd  ()  ; 

The  bitmap  is  now  the  responsibility  of  the  clipboard.  Do  not  delete  it!  The  clipboard  will 
delete  the  bitmap  itself  the  next  time  it  gets  an  Empty  Clipboard  call. 

Because  the  clipboard  contains  a  new  bitmap,  BLOWUP2  invalidates  its  own  client 
area,  as  follows: 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 

} 

If  BLOWUP2  wasn’t  successful  in  creating  a  bitmap,  it  beeps: 
el  se 

MessageBeep  (0)  ; 
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Finally,  the  memory  device  context  is  deleted,  and  the  window’s  device  context  is  released: 

DeleteDC  (hdcMem)  ; 

ReleaseDC  (hwnd,  hdc)  ; 

When  BLOWUP2  gets  a  WM_PAINT  message,  it  opens  the  clipboard  and  checks  to 
see  if  a  bitmap  is  available: 

OpenClipboard  (hwnd)  ; 

if  (hBitmap  =  GetCl ipboardData  ( C F_B I TMAP ) ) 

{ 

If  the  clipboard  contains  a  bitmap,  BLOWUP2  creates  a  memory  device  context  and  selects 
the  bitmap  from  the  clipboard  into  the  device  context: 

hdcMem  =  CreateCompatibleDC  (hdc)  ; 

SelectObject  (hdcMem,  hBitmap)  ; 

To  copy  the  dimensions  of  this  bitmap  into  a  BITMAP  structure,  BLOWTJP2  uses 
GetObject : 

GetObject  (hBitmap,  sizeof  (BITMAP),  ( LPSTR)  &bm)  ; 

It  can  then  copy  the  bitmap  to  the  client  area,  stretching  it  to  the  larger  or  smaller 
dimensions: 

SetStretchBl tMode  (hdc,  C0L0R0NC0L0R)  ; 

StretchBlt  (hdc,  0,  0,  xClient,  yClient, 

hdcMem,  0,  0,  bm.bmWidth,  bm.bmHeight,  SRCCOPY)  ; 

The  only  cleanup  involved  is  deleting  the  memory  device  context: 

DeleteDC  (hdcMem)  ; 

} 

and  closing  the  clipboard: 

CloseClipboard  0  ; 

The  bitmap  isn’t  deleted  because  it  belongs  to  the  clipboard. 

If  we  wanted  to  make  an  exact  copy  of  the  bitmap,  we  could  use  GetObject  to  obtain 
the  dimensions: 

GetObject  (hBitmap,  sizeof  (BITMAP),  (LPSTR)  &bm)  ; 

and  create  a  new  bitmap  and  another  memory  device  context: 

hBitmap2  =  CreateBitmapIndi rect  (&bm)  ; 
hdcMem2  =  CreateCompatibleDC  (hdc)  ; 

SelectObject  (hdcMem2,  hBi tmap2 )  ; 
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A  simple  BitElt  copies  the  bitmap: 

BitBlt  (hdcMem2,  0,  0,  bm.bmWidth,  bm.bmHeight,  hdcMem,  0,  0,  SRCCOPY)  ; 

You  would  then  delete  the  two  memory  device  contexts. 

Although  BLOWUP2  will  display  in  its  client  area  any  bitmap  that  is  currently  in  the 
clipboard,  it  checks  the  contents  of  the  clipboard  only  when  it  gets  a  WM_PAINT  message. 
For  instance,  if  you  draw  something  in  the  Windows  PAINTBRUSH  program,  block  it  out, 
and  copy  it  to  the  clipboard,  BLOWUP2’s  client  area  won’t  show  this  new  bitmap  until 
BLOWUP2  gets  a  WM-PAINT  message.  For  this  reason,  BLOWUP2  isn’t  a  true  clipboard 
viewer.  Well  examine  clipboard  viewers  later  in  this  chapter. 

Programs  that  work  with  device-independent  bitmaps  (DIBs)  can  also  transfer  these 
bitmaps  to  and  obtain  them  from  the  clipboard.  If  your  program  has  a  global  memory 
handle  referencing  a  memory  block  that  contains  a  bitmap  definition  in  DIB  format,  it  can 
simply  pass  the  handle  to  SetClipboardData  with  the  CF_DIB  identifier.  After  closing  the 
clipboard,  the  DIB  memory  block  no  longer  belongs  to  your  program.  If  your  program 
needs  to  keep  a  copy  of  the  DIB,  it  can  make  a  copy  for  the  clipboard  by  allocating 
a  memory  block  of  the  same  size  and  copying  the  DIB  data.  Obtaining  a  DIB  from  the 
clipboard  is  similar  to  obtaining  text  from  the  clipboard,  except  that  the  data  is  not 
O-terminated. 

If  your  program  needs  to  keep  its  own  copy  of  a  bitmap  (in  either  device-indepen¬ 
dent  or  device-dependent  format)  after  passing  a  copy  to  the  clipboard,  you  might  be  using 
lots  of  memory  space  to  store  the  two  copies.  In  this  case,  you’ll  probably  want  to  use  a 
technique  called  “delayed  rendering”  to  avoid  hogging  memory  resources.  Delayed  ren¬ 
dering  is  discussed  later  in  this  chapter. 

The  Metafile  and  the  Metafile  Picture 

Using  the  clipboard  to  transfer  metafiles  from  one  program  to  another  involves  complexi¬ 
ties  not  present  when  dealing  with  text  and  bitmaps.  You  can  determine  the  length  of  a 
NULL-terminated  string  by  simply  searching  for  the  NULL  terminator.  You  can  determine 
the  dimensions  of  a  bitmap  using  GetObject.  But  if  you  have  a  handle  to  a  metafile,  how  can 
you  determine  how  large  the  image  will  be  when  you  play  the  metafile?  Unless  you  start 
digging  into  the  internals  of  the  metafile  itself,  you  can’t. 

Moreover,  when  a  program  obtains  a  metafile  from  the  clipboard,  it  has  the  most 
flexibility  in  working  with  it  if  the  metafile  has  been  designed  to  be  played  in  an 
MM_ISOTROPIC  or  MM -ANISOTROPIC  mapping  mode.  The  program  that  receives  the 
metafile  can  then  scale  the  image  by  simply  setting  viewport  extents  before  playing  the 
metafile.  But  if  the  mapping  mode  is  set  to  MM -ISOTROPIC  or  MM -ANISOTROPIC  within 
the  metafile,  then  the  program  that  receives  the  metafile  is  stuck.  The  program  can  make 
GDI  calls  only  before  or  after  the  metafile  is  played.  It  can’t  make  a  GDI  call  in  the  middle 
of  a  metafile. 
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To  solve  these  problems,  metafile  handles  are  not  directly  put  into  the  clipboard  and 
retrieved  by  other  programs.  Instead,  the  metafile  handle  is  part  of  a  “metafile  picture,” 
which  is  a  structure  of  type  METAFILEPICT.  This  structure  allows  the  program  that  ob¬ 
tains  the  metafile  picture  from  the  clipboard  to  set  the  mapping  mode  and  viewport  ex¬ 
tents  itself  before  playing  the  metafile. 

The  METAFILEPICT  structure  is  8  bytes  long  and  has  four  fields:  mm  (int),  the  map¬ 
ping  mode;  xExt  (int)  and  yExt  (int),  the  width  and  height  of  the  metafile  image;  and  hMF 
(WORD),  the  handle  to  the  metafile.  For  all  the  mapping  modes  except  MM -ISOTROPIC 
and  MM_ANISOTROPIC,  the  xExt  and  yExt  values  are  the  size  of  the  image  in  units  of  the 
mapping  mode  given  by  mm.  With  this  information,  the  program  that  copies  the  metafile 
picture  structure  from  the  clipboard  can  determine  how  much  display  space  the  metafile 
will  encompass  when  it  is  played.  The  program  that  creates  the  metafile  can  set  these 
values  to  the  largest  ^-coordinates  and  ^-coordinates  it  uses  in  the  GDI  drawing  functions 
that  enter  the  metafile. 

For  the  MM -ISOTROPIC  and  MM -ANISOTROPIC  mapping  modes,  the  xExt  and 
yExt  fields  function  differently.  You  will  recall  from  Chapter  11  that  a  program  uses  the 
MM-ISOTROPIC  or  MM-ANISOTROPIC  mapping  mode  when  it  wants  to  use  arbitrary 
logical  units  in  GDI  functions  independent  of  the  measurable  size  of  the  image.  A  program 
uses  MM_ISOTROPIC  when  it  wants  to  maintain  an  aspect  ratio  regardless  of  the  size  of 
the  viewing  surface  and  MM -ANISOTROPIC  when  it  doesn’t  care  about  the  aspect  ratio. 
You  will  also  recall  from  Chapter  11  that  after  a  program  sets  the  mapping  mode  to 
MM_ISOTROPIC  or  MM -ANISOTROPIC,  it  generally  makes  calls  to  SetWindowExt  and 
SetViewportExt.  The  SetWindowExt  call  uses  logical  units  to  specify  the  units  the  program 
wants  to  use  when  drawing.  The  SetViewportExt  call  uses  device  units  based  on  the  size  of 
the  viewing  surface  (for  instance,  the  size  of  the  window’s  client  area). 

If  a  program  creates  an  MM -ISOTROPIC  or  MM -ANISOTROPIC  metafile  for  the 
clipboard,  then  the  metafile  should  not  itself  contain  a  call  to  SetViewportExt  because  the 
device  units  in  that  call  would  be  based  on  the  display  surface  of  the  program  creating  the 
metafile  and  not  on  the  display  surface  of  the  program  that  reads  the  metafile  from  the 
clipboard  and  plays  it.  Instead,  the  xExt  and  yExt  values  should  assist  the  program  that 
obtains  the  metafile  from  the  clipboard  in  setting  appropriate  viewport  extents  for  play¬ 
ing  the  metafile.  But  the  metafile  itself  contains  a  call  to  set  the  window  extent  when  the 
mapping  mode  is  MM -ISOTROPIC  or  MM -ANISOTROPIC.  The  coordinates  of  the  GDI 
drawing  functions  within  the  metafile  are  based  on  these  window  extents. 

The  program  that  creates  the  metafile  and  metafile  picture  follows  these  rules: 

■  The  mm  field  of  the  METAFILEPICT  structure  is  set  to  specify  the  map¬ 
ping  mode. 

■  For  mapping  modes  other  than  MM -ISOTROPIC  and  MM-ANISOTRO¬ 
PIC,  the  xExt  and  yExt  fields  are  set  to  the  width  and  height  of  the  image 
in  units  corresponding  to  the  mm  field.  For  metafiles  to  be  played  in  an 
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MM -ISOTROPIC  or  MM -ANISOTROPIC  environment,  matters  get  a  little 
more  complex.  For  MM -ANISOTROPIC,  0  values  of  xExt  and  yExt  are 
used  when  the  program  is  suggesting  neither  a  size  nor  an  aspect  ratio  for 
the  image.  For  MM -ISOTROPIC  or  MM -ANISOTROPIC,  positive  values 
of  xExt  and  yExt  indicate  a  suggested  width  and  height  of  the  image  in 
units  of  0.01  mm  (MM-HIMETRIC  units).  For  MM-ISOTROPIC,  negative 
values  of  xExt  and  yExt  indicate  a  suggested  aspect  ratio  of  the  image  but 
not  a  suggested  size. 

■  For  the  MM_ISOTROPIC  and  MM-ANISOTROPIC  mapping  modes,  the 
metafile  itself  contains  calls  to  SetWindowExt  and  (possibly)  Set- 
WindowOrg.  That  is,  the  program  that  creates  the  metafile  calls  these 
functions  in  the  metafile  device  context.  Generally,  the  metafile  will  not 
contain  calls  to  SetMapMode ,  SetViewportExt,  or  SetViewportOrg. 

■  The  metafile  should  be  a  memory-based  metafile,  not  a  disk-based 
metafile. 

Here’s  some  sample  code  for  a  program  creating  a  metafile  and  copying  it  to  the  clip¬ 
board.  If  the  metafile  uses  the  MM -ISOTROPIC  or  MM -ANISOTROPIC  mapping  mode, 
the  first  calls  in  the  metafile  should  be  to  set  the  window  extent.  (The  window  extent  is 
fixed  in  the  other  mapping  modes.)  Regardless  of  the  mapping  mode,  the  window  origin 
can  also  be  set: 

hdcMeta  =  CreateMetaFi 1 e  (NULL)  ; 

SetWindowExt  (hdcMeta,  ...)  ; 

SetWindowOrg  (hdcMeta,  ...)  ; 

The  coordinates  in  the  drawing  functions  of  the  metafile  are  based  on  these  window  ex¬ 
tents  and  the  window  origin.  After  the  program  uses  GDI  calls  to  draw  on  the  metafile 
device  context,  the  metafile  is  closed  to  get  a  handle  to  the  metafile: 

hmf  =  CloseMetaFile  (hdcMeta)  ; 

The  program  also  needs  to  define  a  far  pointer  to  a  structure  of  type  METAFILEPICT 
and  allocate  a  block  of  global  memory  for  this  structure: 

GLOBALHANDLE  hGMem  ; 

LPMETAFI LEPICT  lpMFP  ; 

[other program  lines] 

hGMem  =  GlobalAlloc  (GHND,  (DWORD)  sizeof  (METAFILEPICT))  ; 

lpMFP  =  ( LPMETAFILEPICT)  G1 obal Lock  (hGMem)  ; 
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Next,  the  program  sets  the  four  fields  of  this  structure: 

lpMFP->mm  =  MM_. . .  ; 

1 pMFP - >xExt  =  . . .  ; 

1 pMFP - >y Ext  =  . . .  ; 

1 pMFP->hMF  =  hmf  ; 

GlobalUnlock  (hGMem)  ; 

The  program  then  transfers  the  global  memory  block  containing  the  metafile  picture 
structure  to  the  clipboard: 

OpenCl ipboard  (hwnd)  ; 

EmptyClipboard  0  ; 

SetCl i pboardData  (CF.METAFILEPICT,  hGMem)  ; 

Closed  ipboard  0  ; 

Following  these  calls,  the  hGMem  handle  (the  memory  block  containing  the  metafile  pic¬ 
ture  structure)  and  the  hmf  handle  (the  metafile  itself)  become  invalid  for  the  program 
that  created  them. 

Now  for  the  hard  part.  When  a  program  obtains  a  metafile  from  the  clipboard  and 
plays  this  metafile,  the  following  steps  must  take  place: 

1.  The  program  uses  the  mm  field  of  the  metafile  picture  structure  to  set  the 
mapping  mode. 

2.  For  mapping  modes  other  than  MM_ISOTROPIC  or  MM -ANISOTROPIC, 
the  program  uses  the  xExt  and  yExt  values  to  set  a  clipping  rectangle  or 
simply  to  determine  the  size  of  the  image.  For  the  MM_ISOTROPIC  and 
MM -ANISOTROPIC  mapping  modes,  the  program  uses  xExt  and  yExt 
to  set  the  viewport  extents. 

3.  The  program  then  plays  the  metafile. 

Here’s  the  code.  You  first  open  the  clipboard,  get  the  handle  to  the  metafile  picture 
structure,  and  lock  it: 

OpenCl i pboa rd  (hwnd)  ; 

hGMem  =  GetCl i pboardData  (CF.METAFILEPICT)  ; 

1 pMFP  =  ( LPMETAFILEPICT)  G1 obal Lock  (hGMem)  ; 

You  can  then  save  the  attributes  of  your  current  device  context  and  set  the  mapping  mode 
to  the  mm  value  of  the  structure: 

SaveDC  (hdc)  ; 

SetMappingMode  ( 1 pMFP - >mm)  ; 

If  the  mapping  mode  isn’t  MM-ISOTROPIC  or  MM -ANISOTROPIC,  you  can  set  a 
clipping  rectangle  to  the  values  of  xExt  and  yExt .  Because  these  values  are  in  logical  units, 
you  have  to  use  LPtoDP  to  convert  the  coordinates  to  device  units  for  the  clipping  rect¬ 
angle.  Or  you  can  simply  save  the  values  so  that  you  know  how  large  the  image  is. 
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For  the  MM -ISOTROPIC  or  MM -ANISOTROPIC  mapping  mode,  you  use  xExt  and 
yExt  to  set  the  viewport  extent.  One  possible  function  to  perform  this  task  is  shown  below. 
This  function  assumes  that  cxClient  and  cyClient  represent  the  pixel  height  and  width  of 
the  area  in  which  you  want  the  metafile  to  appear  if  no  suggested  size  is  implied  by  xExt 
and  yExt. 

void  PrepareMetaFile  (HDC  hdc,  LPMETAFI LEPICT  lpmfp, 

SHORT  cxClient,  SHORT  cyClient) 

{ 

long  xlScale,  ylScale,  1  Seal e  ; 

SetMapMode  (hdc,  1 pmf p - >mm )  ; 

if  (1 pmfp->mm  ==  MM.ISOTROPIC  !!  lpmfp->mm  ==  MM_AN I SOTROP I C ) 

{ 

if  ( 1 pmf p->xExt  ==  0) 

SetViewportExt  (hdc,  cxClient,  cyClient)  ; 
else  if  (lpmfp->xExt  >  0) 

SetViewportExt  (hdc, 

(short)  (dong)  lpmfp->xExt  * 

GetDeviceCaps  (hdc,  HORZRES)  / 

GetDeviceCaps  (hdc,  HORZSIZE)  /  100), 

(short)  ((long)  lpmfp->yExt  * 

GetDeviceCaps  (hdc,  VERTRES)  / 

GetDeviceCaps  (hdc,  VERTSIZE)  /  100))  ; 

else  if  (lpmfp->xExt  <  0) 

{ 

xlScale  =  100L  *  (long)  cxClient  * 

GetDeviceCaps  (hdc,  HORZSIZE)  / 

GetDeviceCaps  (hdc,  HORZRES)  / 

-lpmfp->xExt  ; 

ylScale  =  100L  *  (long)  cyClient  * 

GetDeviceCaps  (hdc,  VERTSIZE)  / 

GetDeviceCaps  (hdc,  VERTRES)  / 

-1 pmfp->yExt  ; 

1  Seal e  =  min  (xlScale,  ylScale)  ; 

SetViewportExt  (hdc, 

(short)  ((long)  -lpmfp->xExt  *  1  Seal e  * 

GetDeviceCaps  (hdc,  HORZRES)  / 

GetDeviceCaps  (hdc,  HORZSIZE)  /  100), 

(short)  ((long)  -1 pmfp->yExt  *  1  Seal e  * 

GetDeviceCaps  (hdc,  VERTRES)  / 

GetDeviceCaps  (hdc,  VERTSIZE)  /  100))  ; 

} 

} 

} 
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This  code  assumes  that  both  xExt  and  yExt  are  0,  greater  than  0,  or  less  than  0, 
(which  should  be  the  case).  If  the  extents  are  0,  no  size  or  aspect  ratio  is  suggested.  The 
viewport  extents  are  set  to  the  area  in  which  you  want  to  display  the  metafile.  Positive 
values  of  xExt  and  yExt  are  a  suggested  image  size  in  units  of  0.01  mm.  The  GetDeviceCaps 
function  assists  in  determining  the  number  of  pixels  per  0.01  mm,  and  this  value  is 
multiplied  by  the  extent  values  in  the  metafile  picture  structure.  Negative  values  of  xExt 
and  yExt  indicate  a  suggested  aspect  ratio  but  not  a  suggested  size.  The  value  iScale  is  first 
calculated  based  on  the  aspect  ratio  of  the  size  in  millimeters  corresponding  to  cxClient 
and  cyClient.  This  scaling  factor  is  then  used  to  set  a  viewport  extent  in  pixels. 

With  this  job  out  of  the  way,  you  can  set  a  viewport  origin  if  you  want,  play  the 
metafile,  and  return  the  device  context  to  normal: 

PlayMetaFile  (1 pMFP->hMF)  ; 

RestoreDC  (hdc,  -1)  ; 

Then  you  unlock  the  memory  block  and  close  the  clipboard: 

G1 obal Unlock  (hGMem)  ; 

CloseClipboard  0  ; 


BEYOND  SIMPLE  CLIPBOARD  USE 

In  using  text  and  bitmaps,  you’ve  seen  that  transferring  data  to  the  clipboard  requires  four 
calls  after  the  data  has  been  prepared: 

OpenCl ipboard  (hwnd)  ; 

EmptyClipboard  0  ; 

SetClipboardData  (wFormat,  hHandle)  ; 

CloseClipboard  0  ; 

Getting  access  to  this  data  requires  three  calls: 

OpenCl ipboard  (hwnd)  ; 

hHandle  =  GetCl ipboardData  (wFormat)  ; 

[other program  lines] 

CloseClipboard  0  ; 

You  can  make  a  copy  of  the  clipboard  data  or  use  it  in  some  other  manner  between  the 
GetClipboardData  and  CloseClipboard  calls.  That  approach  may  be  all  you’ll  need  for 
most  purposes,  but  you  can  also  use  the  clipboard  in  more  sophisticated  ways. 

Using  Multiple  Data  Items 

When  you  open  the  clipboard  to  put  data  into  it,  you  must  call  EmptyClipboard  to  signal 
Windows  to  free  or  delete  the  contents  of  the  clipboard.  You  can’t  add  something  to  the 
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existing  contents  of  the  clipboard.  So  in  this  sense,  the  clipboard  holds  only  one  item  at 
a  time. 

However,  between  the  EmptyClipboard  and  the  CloseClipboard  calls,  you  can  call 
SetClipboardData  several  times,  each  time  using  a  different  clipboard  format.  For  in¬ 
stance,  if  you  want  to  store  a  short  string  of  text  in  the  clipboard,  you  can  create  a  metafile 
device  context  and  write  that  text  to  the  metafile.  You  can  also  create  a  bitmap  large 
enough  to  hold  the  character  string,  select  the  bitmap  into  a  memory  device  context,  and 
write  the  string  to  the  bitmap.  In  this  way,  you  make  that  character  string  available  not  only 
to  programs  that  can  read  text  from  the  clipboard  but  also  to  programs  that  read  bitmaps 
and  metafiles  from  the  clipboard.  Moreover,  if  you  select  a  different  font  into  the  metafile 
device  context  or  memory  device  context  before  writing  the  text,  programs  that  read  bit¬ 
maps  or  metafiles  will  use  the  string  with  this  different  font.  (Of  course,  these  programs 
won’t  be  able  to  recognize  the  metafile  or  bitmap  as  actually  containing  a  character  string.) 

If  you  want  to  write  several  handles  to  the  clipboard,  you  call  SetClipboardData  for 
each  of  them: 

OpenCl i pboa rd  (hwnd)  ; 

EmptyClipboard  ()  ; 

SetClipboardData  (CF_TEXT,  hGMemText)  ; 

SetClipboardData  (CF_BITMAP,  hBitmap)  ; 

SetClipboardData  (CF.METAFI LEPICT,  hGMemMFP)  ; 

CloseClipboard  ()  ; 

While  these  three  formats  of  data  are  in  the  clipboard,  an  IsClipboardFor  mat  Available 
call  with  the  CF_TEXT,  CF_BITMAP,  or  CF_METAFILEPICT  argument  will  return  TRUE. 
A  program  can  get  access  to  these  handles  by  calling: 

hGMemText  =  GetCl i pboardData  ( C F_T EXT)  ; 


or: 


hBitmap  =  GetCl i pboardData  (CF_BITMAP)  ; 

or: 

hGMemMFP  =  GetCl i pboardData  (CF_METAFI LEPICT)  ; 

The  next  time  a  program  calls  EmptyClipboard ,  Windows  will  free  or  delete  all  three  of  the 
handles  retained  by  the  clipboard  as  well  as  the  metafile  that  is  part  of  the  METAFILEPICT 
structure. 

A  program  can  determine  all  the  formats  stored  by  the  clipboard  by  first  opening 
the  clipboard  and  then  calling  EnumClipboardFormats.  Start  off  by  setting  a  variable 
wFormat  to  0: 


810 


Chapter  16:  The  Clipboard 


wFormat  =  0  ; 

OpenClipboard  (hwnd)  ; 

Now  make  successive  EnumClipboardFormats  calls  starting  with  the  0  value.  The  func¬ 
tion  will  return  a  positive  wFormat  value  for  each  format  currently  in  the  clipboard.  When 
the  function  returns  0,  you’re  done: 

while  (wFormat  =  EnumClipboardFormats  (wFormat)) 

{ 

[logic  for  each  wFormat  value] 

} 

CloseClipboard  0  ; 

You  can  obtain  the  number  of  different  formats  currently  in  the  clipboard  by  calling: 
nCount  =  CountClipboardFormats  0  ; 

Delayed  Rendering 

When  you  put  data  into  the  clipboard,  you  generally  make  a  copy  of  the  data  and  give  the 
clipboard  a  handle  to  a  global  memory  block  that  contains  the  copy.  For  very  large  data 
items,  this  approach  can  waste  memory.  If  the  user  never  pastes  that  data  into  another  pro¬ 
gram,  it  will  continue  to  occupy  memory  space  until  it  is  replaced  by  something  else. 

You  can  avoid  this  problem  by  using  a  technique  called  “delayed  rendering,”  in 
which  your  program  doesn’t  actually  supply  the  data  until  another  program  needs  it. 
Rather  than  give  Windows  a  handle  to  the  data,  you  simply  use  a  NULL  in  the  SetClip- 
boardData  call: 

OpenClipboard  (hwnd)  ; 

EmptyClipboard  0  ; 

SetCl ipboardData  (wFormat,  NULL)  ; 

CloseClipboard  0  ; 

You  can  have  multiple  SetClipboardData  calls  using  different  values  of  wFormat.  You  can 
use  NULL  parameters  with  some  of  them  and  real  handles  with  others. 

That’s  simple  enough,  but  now  the  process  gets  a  little  more  complex.  When  another 
program  calls  GetClipboardData,  Windows  will  check  to  see  if  the  handle  for  that  format  is 
NULL.  If  it  is,  Windows  will  send  a  message  to  the  “clipboard  owner”  (your  program) 
asking  for  a  real  handle  to  the  data.  Your  program  must  then  supply  this  handle. 

More  specifically,  the  “clipboard  owner”  is  the  last  window  that  put  data  into  the 
clipboard.  When  a  program  calls  OpenClipboard ,  Windows  stores  the  window  handle  re¬ 
quired  by  this  function.  This  handle  identifies  the  window  that  has  the  clipboard  open. 
On  receipt  of  an  EmptyClipboard  call,  Windows  establishes  this  window  as  the  new  clip¬ 
board  owner. 
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A  program  that  uses  delayed  rendering  has  to  process  three  messages  in  its  window 
procedure:  WM-RENDERFORMAT,  WM.RENDERALLFORMATS,  and  WM.DESTROY- 
CLIPBOARD.  Windows  sends  your  window  procedure  a  WM-RENDERFORMAT  message 
when  another  program  calls  GetClipboardData.  The  value  of  wParam  is  the  format  re¬ 
quested.  When  you  process  the  WM_RENDERFORMAT  message,  don’t  open  and  empty 
the  clipboard.  Simply  create  a  global  memory  block  for  the  format  given  by  wParam ,  trans¬ 
fer  the  data  to  it,  and  call  SetClipboardData  with  the  correct  format  and  the  global  handle. 
Obviously,  you’ll  need  to  retain  information  in  your  program  in  order  to  construct  this  data 
properly  when  processing  WM_RENDERFORMAT.  When  another  program  calls  Empty- 
Clipboard ,  Windows  sends  your  program  a  WM_DESTROYCLIPBOARD  message.  This 
tells  you  that  the  information  to  construct  the  clipboard  data  is  no  longer  needed.  You  are 
no  longer  the  clipboard  owner. 

If  your  program  terminates  while  it  is  still  the  clipboard  owner,  and  the  clipboard 
still  contains  NULL  data  handles  that  your  program  set  with  SetClipboardData ,  you’ll 
receive  a  WM -RENDER ALLFORMATS  message.  You  should  open  the  clipboard,  empty  it, 
put  the  data  in  global  memory  blocks,  and  call  SetClipboardData  for  each  format.  Then 
close  the  clipboard.  The  WM -RENDER  ALLFORM  ATS  message  is  one  of  the  last  messages 
your  window  procedure  receives.  It  is  followed  by  a  WM_DESTROYCLIPBOARD  message 
(because  you’ve  rendered  all  the  data)  and  then  the  normal  WM-DESTROY. 

If  your  program  can  transfer  only  one  format  of  data  to  the  clipboard  (text,  for  in¬ 
stance),  you  can  combine  the  WM  .RENDER  ALLFORM  ATS  and  WM-RENDERFORMAT 
processing.  The  code  will  look  something  like  this: 

case  WM_RENDERALL FORMATS  : 

OpenCl ipboard  (hwnd)  ; 

EmptyCl ipboard  0  ; 

//  fall  through 

case  WM.RENDERFORMAT  : 

[put  text  into  global  memory  block] 

SetClipboardData  (CF_TEXT,  hMem)  ; 

if  (iMessage  ==  WM_RENDERALL FORMATS) 

CloseClipboard  ()  ; 
return  0  ; 

If  your  program  uses  several  clipboard  formats,  then  you  will  want  to  process  the 
WM-RENDERFORMAT  message  only  for  the  format  requested  by  wParam.  You  don’t  need 
to  process  the  WM.DESTROYCLIPBOARD  message  unless  it  is  burdensome  for  your  pro¬ 
gram  to  retain  the  information  necessary  to  construct  the  data. 
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Private  Data  Formats 

So  far  we’ve  dealt  with  only  the  standard  clipboard  formats  defined  by  Windows.  However, 
you  may  want  to  use  the  clipboard  to  store  a  “private  data  format.”  The  Windows  WRITE 
program  uses  this  technique  to  store  text  that  contains  font  and  formatting  information. 

At  first,  this  concept  may  seem  nonsensical.  If  the  purpose  of  the  clipboard  is  to 
transfer  data  between  applications,  why  should  the  clipboard  contain  data  that  only  one 
application  understands?  The  answer  is  simple:  The  clipboard  also  exists  to  allow  the 
transfer  of  data  between  different  instances  of  the  same  program,  and  these  instances 
obviously  understand  the  same  private  formats. 

There  are  several  ways  to  use  private  data  formats.  The  easiest  involves  data  that  is 
ostensibly  in  one  of  the  standard  clipboard  formats  (text,  bitmap,  or  metafile)  but  that  has 
meaning  only  to  your  program.  In  this  case,  you  use  one  of  the  following  wFormat  values 
in  your  SetClipboardData  and  GetClipboardData  calls:  CF-DSPTEXT,  CF_DSPBITMAP, 
or  CF_DSPMETAFILEPICT.  The  letters  DSP  stand  for  “display” — these  formats  allow  CLIP¬ 
BOARD  to  display  the  data  as  text,  a  bitmap,  or  a  metafile.  However,  another  program  that 
calls  GetClipboardData  using  the  normal  CF_TEXT,  CF-BITMAP,  or  CF_METAFILEPICT 
format  won’t  obtain  this  data. 

If  you  use  one  of  these  formats  to  put  data  in  the  clipboard,  you  must  also  use  the 
same  format  to  get  the  data  out.  But  how  do  you  know  if  the  data  is  from  another  instance 
of  your  program  or  from  another  program  using  one  of  these  formats?  Here’s  one  way:  You 
can  first  obtain  the  clipboard  owner  by  calling: 

hwndCl ipOwner  =  GetCl ipboardOwner  ()  ; 

You  can  then  get  the  name  of  the  window  class  of  this  window  handle: 

char  szClassName  [16]  ; 

[other program  lines] 

GetClassName  (hwndClipOwner,  &szCl assName,  16)  ; 

If  the  class  name  is  the  same  as  your  program’s,  then  the  data  was  put  in  the  clipboard  by 
another  instance  of  your  program. 

The  second  way  to  use  private  formats  involves  the  CF_OWNERDISPLAY  flag.  The 
global  memory  handle  to  SetClipboardData  is  NULL: 

SetClipboardData  ( CF_OWNERDI SPLAY ,  NULL)  ; 

This  is  the  method  that  WRITE  uses  to  show  formatted  text  in  the  client  area  of  the  CLIP¬ 
BOARD  clipboard  viewer.  Obviously,  CLIPBRD.EXE  doesn’t  know  how  to  display  this  for¬ 
matted  text.  When  WRITE  specifies  the  CF-OWNERDISPLAY  format,  WRITE  is  taking 
responsibility  for  painting  CLIPBOARD’S  client  area. 
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Because  the  global  memory  handle  is  NULL,  a  program  that  calls  SetClipboardData 
with  the  CF_OWNERDISPLAY  format  (the  clipboard  owner)  must  process  the  delayed 
rendering  messages  sent  to  the  clipboard  owner  by  Windows  as  well  as  five  additional 
messages.  These  five  messages  are  sent  by  the  clipboard  viewer  to  the  clipboard  owner: 

■  WM_ASKCBFORMATNAME — The  clipboard  viewer  sends  this  message 
to  the  clipboard  owner  to  get  a  name  for  the  format  of  the  data.  The 
IParam  parameter  is  a  pointer  to  a  buffer,  and  wParam  is  the  maximum 
number  of  characters  for  this  buffer.  The  clipboard  owner  must  copy  the 
name  of  the  clipboard  format  into  this  buffer. 

■  WM-SIZECLIPBOARD — This  message  tells  the  clipboard  owner  that  the 
size  of  the  clipboard  viewer’s  client  area  has  changed.  The  wParam 
parameter  is  a  handle  to  the  clipboard  viewer,  and  IParam  is  a  pointer  to  a 
RECT  structure  containing  the  new  size.  If  the  RECT  structure  contains  all 
zeros,  the  clipboard  viewer  is  being  destroyed  or  made  an  icon.  Although 
CLIPBRD.EXE  allows  only  one  instance  of  itself  to  be  running,  other 
clipboard  viewers  can  also  send  this  message  to  the  clipboard  owner. 
Handling  these  multiple  clipboard  viewers  isn’t  impossible  for  the  clip¬ 
board  owner  (given  that  wParam  identifies  the  particular  viewer),  but  it 
isn’t  easy,  either. 

■  WM-PAINTCLIPBOARD — This  message  tells  the  clipboard  owner  to 
update  the  clipboard  viewer’s  client  area.  Again,  wParam  is  a  handle 
to  the  clipboard  viewer’s  window.  The  IParam  parameter  is  a  pointer  to  a 
PAINTSTRUCT  structure.  The  clipboard  owner  can  obtain  a  handle  to  the 
clipboard  viewer’s  device  context  from  the  hdc  field  of  this  structure. 

■  WM_HSCROLLCLIPBOARD  and  WM-VSCROLLCLIPBOARD— These 
messages  inform  the  clipboard  owner  that  a  user  has  scrolled  the 
clipboard  viewer’s  scroll  bars.  The  wParam  parameter  is  a  handle  to  the 
clipboard  viewer’s  window,  the  low  word  of  IParam  is  the  scrolling 
request  (the  same  as  wParam  in  normal  scroll  bar  messages),  and  the  high 
word  of  IParam  is  the  thumb  position  if  the  low  word  is  SB  -THUMB- 
POSITION.  (This  value  is  the  same  as  the  low  word  of  IParam  in  a  normal 
scroll  bar  message.) 

Handling  these  messages  may  look  like  more  trouble  than  it’s  worth.  However,  the  process 
does  provide  a  benefit  to  the  user:  When  copying  text  from  WRITE  to  the  clipboard,  the 
user  will  find  it  comforting  to  see  the  text  still  formatted  in  CLIPBOARD’S  client  area. 

The  third  way  to  use  private  clipboard  data  formats  is  to  register  your  own  clipboard 
format  name.  You  supply  a  name  for  this  format  to  Windows,  and  Windows  gives  your  pro¬ 
gram  a  number  to  use  as  the  format  parameter  in  SetClipboardData  and  GetClipboard- 
Data.  Programs  that  use  this  method  generally  also  copy  data  to  the  clipboard  in  one  of  the 
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standard  formats.  This  approach  allows  CLIPBRD.EXE  to  display  data  in  its  client  area 
(without  the  hassles  involved  with  CF_OWNERDISPLAY)  and  permits  other  programs  to 
copy  data  from  the  clipboard. 

As  an  example,  let’s  assume  we’ve  written  a  vector  drawing  program  that  copies  data 
to  the  clipboard  in  a  bitmap  format,  a  metafile  format,  and  its  own  registered  clipboard  for¬ 
mat.  CLIPBRD.EXE  will  display  the  metafile.  Other  programs  that  can  read  bitmaps  or 
metafiles  from  the  clipboard  will  obtain  those  formats.  However,  when  the  vector  drawing 
program  itself  needs  to  read  data  from  the  clipboard,  it  will  copy  the  data  in  its  own 
registered  format  because  that  format  probably  contains  more  information  than  the  bitmap 
or  metafile. 

A  program  registers  a  new  clipboard  format  by  calling: 

wFormat  =  Regi sterCl i pboardFormat  (IpszFormatName)  ; 

The  wFormat  value  is  between  OxCOOO  and  OxFFFF.  A  clipboard  viewer  (or  a  program  that 
obtains  all  the  current  clipboard  formats  by  calling  EnumClipboardFor  mats')  can  obtain 
the  ASCII  name  of  this  format  by  calling: 

GetClipboardFormatName  (wFormat,  IpsBuffer,  nMaxCount)  ; 

Windows  copies  up  to  nMaxCount  characters  into  IpsBuffer. 

Programmers  who  use  this  method  for  copying  data  to  the  clipboard  might  want  to 
publicize  the  format  name  and  the  actual  format  of  the  data.  If  the  program  becomes  popu¬ 
lar,  other  programs  can  then  copy  data  in  this  format  from  the  clipboard. 

BECOMING  A  CLIPBOARD  VIEWER 

A  program  that  is  notified  of  changes  in  the  clipboard  contents  is  called  a  “clipboard 
viewer.”  The  CLIPBOARD  program  that  comes  with  Windows  is  a  clipboard  viewer,  but 
you  can  also  write  your  own  clipboard  viewer  program.  Clipboard  viewers  are  notified  of 
changes  to  the  clipboard  through  messages  to  the  viewer’s  window  procedure. 

The  Clipboard  Viewer  Chain 

Any  number  of  clipboard  viewer  applications  can  be  running  in  Windows  at  the  same  time, 
and  they  can  all  be  notified  of  changes  to  the  clipboard.  From  Windows’  perspective,  how¬ 
ever,  there  is  only  one  clipboard  viewer,  which  I’ll  call  the  “current  clipboard  viewer.” 
Windows  maintains  only  one  window  handle  to  identify  the  current  clipboard  viewer,  and 
it  sends  messages  only  to  that  window  when  the  contents  of  the  clipboard  change. 

Clipboard  viewer  applications  have  the  responsibility  of  participating  in  the  “clip¬ 
board  viewer  chain”  so  that  all  running  clipboard  viewer  programs  receive  the  messages 
that  Windows  sends  to  the  current  clipboard  viewer.  When  a  program  registers  itself  as  a 
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clipboard  viewer,  that  program  becomes  the  current  clipboard  viewer.  Windows  gives  that 
program  the  window  handle  of  the  previous  current  clipboard  viewer,  and  the  program 
saves  this  handle.  When  the  program  receives  a  clipboard  viewer  message,  it  sends  that 
message  to  the  window  procedure  of  the  next  program  in  the  clipboard  chain. 

Clipboard  Viewer  Functions  and  Messages 

A  program  can  become  part  of  the  clipboard  viewer  chain  by  calling  the  SetClip- 
boardViewer  function.  If  the  primary  purpose  of  the  program  is  to  serve  as  a  clipboard 
viewer,  the  program  can  call  this  function  during  processing  of  the  WM-CREATE  message. 
The  function  returns  the  window  handle  of  the  previous  current  clipboard  viewer.  The 
program  should  save  that  handle  in  a  static  variable: 

static  HWND  hwndNextViewer  ; 

[other program  lines] 

case  WM_CREATE  : 

[other program  lines] 

hwndNextViewer  =  SetCl i pboardVi ewer  (hwnd)  ; 

If  your  program  is  the  first  program  to  become  a  clipboard  viewer  during  the  Windows  ses¬ 
sion,  then  hwndNextViewer  will  be  NULL. 

Windows  sends  a  WM_DRAWCLIPBOARD  message  to  the  current  clipboard  viewer 
(the  most  recent  window  to  register  itself  as  a  clipboard  viewer)  whenever  the  contents  of 
the  clipboard  change.  Each  program  in  the  clipboard  viewer  chain  should  use  SendMessage 
to  pass  this  message  to  the  next  clipboard  viewer.  The  last  program  in  the  clipboard 
viewer  chain  (the  first  window  to  register  itself  as  a  clipboard  viewer)  will  have  stored  a 
NULL  hwndNextViewer  value.  If  hwndNextViewer  is  NULL,  the  program  simply  returns 
without  sending  the  message  to  another  program.  (Don’t  confuse  the  WM_DRAWCLIP- 
BOARD  and  WM.PAINTCLIPBOARD  messages.  The  WM_PAINTCLIPBOARD  message  is 
sent  by  a  clipboard  viewer  to  programs  that  use  the  CF_OWNERDISPLAY  clipboard  for¬ 
mat.  The  WM_DRAWCLIPBOARD  message  is  sent  by  Windows  to  the  current  clipboard 
viewer.) 

The  easiest  way  to  process  the  WM_DRAWCLIPBOARD  message  is  to  send  the  mes¬ 
sage  to  the  next  clipboard  viewer  (unless  hwndNextViewer  is  NULL)  and  invalidate  the 
client  area  of  your  window: 

case  WM_DRAWCLI PBOARD  : 
if  (hwndNextViewer) 

SendMessage  (hwndNextViewer,  iMessage,  wParam,  IParam)  ; 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 
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During  processing  of  the  WM_PAINT  message,  you  can  read  the  contents  of  the  clipboard 
by  using  the  normal  OpenClipboard,  GetClipboardData ,  and  CloseClipboard  calls. 

When  a  program  wants  to  remove  itself  from  the  clipboard  viewer  chain,  it  must  call 
ChangeClipboardChain.  This  function  requires  the  window  handle  of  the  program  leav¬ 
ing  the  viewer  chain  and  the  window  handle  of  the  next  clipboard  viewer: 

ChangeClipboardChain  (hwnd,  hwndNextViewer)  ; 

When  a  program  calls  ChangeClipboardChain ,  Windows  sends  a  WM_CHANGECLIP- 
BOARD  message  to  the  current  clipboard  viewer.  The  wParam  parameter  is  the  handle  of 
the  window  removing  itself  from  the  chain  (the  first  parameter  to  ChangeClip¬ 
boardChain),  and  the  low  word  of  iParam  is  the  window  handle  of  the  next  clipboard 
viewer  after  the  one  removing  itself  from  the  chain  (the  second  parameter  to  Change¬ 
ClipboardChain ). 

When  your  program  receives  a  WM_CHANGECLIPBOARD  message,  you  must  there¬ 
fore  check  to  see  if  wParam  is  equal  to  the  value  of  hwndNextViewer  that  you’ve  saved.  If  it 
is,  your  program  must  set  hwndNextViewer  to  the  low  word  of  IParam.  This  action  ensures 
that  any  future  WM_DRAWCLIPBOARD  messages  you  get  won’t  be  sent  to  the  window 
removing  itself  from  the  clipboard  viewer  chain.  If  wParam  isn’t  equal  to  hwndNext¬ 
Viewer ;  and  hwndNextViewer  isn’t  NULL,  send  the  message  to  the  next  clipboard  viewer: 

case  WM_CHANGECBCHAIN  : 

if  (wParam  ==  hwndNextViewer) 

hwndNextViewer  =  LOWORD  (IParam)  ; 

else  if  (hwndNextViewer) 

SendMessage  (hwndNextViewer,  iMessage,  wParam,  IParam)  ; 
return  0  ; 

You  shouldn’t  need  to  include  the  else  if  statement,  which  checks  hwndNextViewer  for  a 
non-NULL  value.  A  NULL  hwndNextViewer  value  would  indicate  that  the  program  execut¬ 
ing  this  code  is  the  last  viewer  on  the  chain,  in  which  case  the  message  should  never  have 
gotten  this  far. 

If  your  program  is  still  in  the  clipboard  viewer  chain  when  it  is  about  to  terminate,  you 
must  remove  it  from  the  chain.  You  can  do  this  during  processing  of  the  WM_DESTROY 
message  by  calling  ChangeClipboardChain : 

case  WM_DESTROY  : 

ChangeClipboardChain  (hwnd,  hwndNextViewer)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

Windows  also  has  a  function  that  allows  a  program  to  obtain  the  window  handle  of 
the  first  clipboard  viewer: 

hwndViewer  =  GetCl ipboardViewer  0  ; 

This  function  isn’t  normally  needed.  The  return  value  can  be  NULL  if  there  is  no  current 
clipboard  viewer. 
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Here’s  an  example  to  illustrate  how  the  clipboard  viewer  chain  works.  When  Win¬ 
dows  first  starts  up,  the  current  clipboard  viewer  is  NULL: 


Current  clipboard  viewer: 

NULL 

A  program  with  a  window  handle  of  hwndl  calls  SetCliphoardViewer.  The  function 
returns  NULL,  which  becomes  the  hwndNextViewer  value  in  this  program: 

Current  clipboard  viewer: 

hwndl 

hwndl’s  next  viewer: 

NULL 

A  second  program,  with  a  window  handle  of  hwnd2,  now  calls  SetCliphoardViewer  and 

gets  back  hwndl : 

Current  clipboard  viewer: 

hwnd2 

hwnd2’s  next  viewer: 

hwndl 

hwndl  's  next  viewer: 

NULL 

A  third  program  ( hwnd3 )  and  then  a  fourth  ( hwnd4 )  also  call  SetCliphoardViewer  and  get 

back  hwnd2  and  hwnd3 : 

Current  clipboard  viewer: 

hwnd4 

bwnd4’s  next  viewer: 

hwnd3 

hwnd3's  next  viewer: 

hwnd2 

hwnd2fs  next  viewer: 

hwndl 

hwndl  fs  next  viewer: 

NULL 

When  the  contents  of  the  clipboard  change,  Windows  sends  a  WM_DRAWCLIPBOARD 
message  to  hwnd4,  hwnd4  sends  the  message  to  hwnd3,  hwnd3  sends  it  to  hwnd2,  hwnd2 
sends  it  to  hwndl,  and  hwndl  returns. 

Now  hwnd2  decides  to  remove  itself  from  the  chain  by  calling: 

Changed i pboardChai n  (hwnd2,  hwndl)  ; 

Windows  sends  hwnd4  a  WM-CHANGECBCHAIN  message  with  wParam  equal  to  hwnd2 
and  the  low  word  of  iParam  equal  to  hwndl.  Because  hwnd4's  next  viewer  is  hwnd3 , 
hwnd4  sends  this  message  to  hwnd3 .  Now  hwnd3  notes  that  wParam  is  equal  to  its  next 
viewer  ( hwnd2 ),  so  it  sets  its  next  viewer  equal  to  the  low  word  of  IParam  ( hwndl )  and 
returns.  The  mission  is  accomplished.  The  clipboard  viewer  chain  now  looks  like  this: 


Current  clipboard  viewer:  hwnd4 

hwnd4’s  next  viewer:  hwnd3 

hwnd3’s  next  viewer:  hwndl 

hwndl ’s  next  viewer:  NULL 


A  Simple  Clipboard  Viewer 

Clipboard  viewers  don’t  have  to  be  as  sophisticated  as  CLIPBRD.EXE.  A  clipboard  viewer 
can,  for  instance,  display  a  single  clipboard  format.  The  CLIPVIEW  program,  shown  in 
Figure  16-2,  is  a  clipboard  viewer  that  displays  only  the  CF_TEXT  format. 
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CLIPVIEW.MAK 

# . . 

#  CLIPVIEW.MAK  make  file 

#  . . 

clipview.exe  :  clipview.obj  clipview.def 

$(WINLINK)  clipview,  clipview,  NUL,  $(WINLIB),  clipview 
re  -t  clipview.exe 

clipview.obj  :  clipview.c 
$ ( WI NCC )  clipview.c 


CLIPVIEW.C 


/*-- . - . - . 

CLIPVIEW.C  --  Simple  Clipboard  Viewer 
(c)  Charles  Petzold,  1992 

*/ 


^include  <windows.h> 
typedef  unsigned  int  UINT  ; 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT.  UINT.  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "ClipView"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.lpszClassName 


CS.HREDRAW  !  CS.VREDRAW  ; 
WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

NULL  ; 

LoadCursor  (NULL,  IDC.ARR0W)  ; 
GetStockObject  (WHITE.BRUSH)  ; 
NULL  ; 
szAppName  ; 


Figure  16-2.  The  CLIPVIEW  program. 


(continued) 
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RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Simple  Clipboard  Viewer  (Text  Only)", 
WS_0V ERLAP PEDW I NDOW , 

CWJJSEDEFAULT,  CW_USEDEFAULT, 

CWJJSEDEFAULT.  CW_USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HWND  hwndNextViewer  ; 

HANDLE  hGMem  ; 

HDC  hdc  ; 

LPSTR  lpGMem  ; 

PAINTSTRUCT  ps  ; 

RECT  rect  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hwndNextViewer  =  SetClipboardViewer  (hwnd)  ; 
return  0  ; 

case  WM.CHANGECBCHAIN  : 

if  (wParam  ==  hwndNextViewer) 

hwndNextViewer  =  LOWORD  (IParam)  ; 

else  if  (hwndNextViewer) 

SendMessage  (hwndNextViewer,  message,  wParam,  IParam)  ; 
return  0  ; 

case  WM.DRAWCLIPBOARD  : 
if  (hwndNextViewer) 

SendMessage  (hwndNextViewer,  message,  wParam,  IParam)  ; 

InvalidateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 
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case  WM_PAINT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

GetClientRect  (hwnd,  &rect)  ; 

OpenClipboard  (hwnd)  ; 

hGMem  =  GetCl ipboardData  (CF_TEXT)  ; 

if  (hGMem  !=  NULL) 

{ 

IpGMem  =  Global  Lock  (hGMem)  ; 

DrawText  (hdc,  IpGMem,  -1,  &rect,  DL.EXPANDTABS)  ; 
GlobalUnlock  (hGMem)  ; 

} 

CloseClipboard  0  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

ChangeClipboardChain  (hwnd,  hwndNextViewer)  ; 
PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


CLIPVIEW.DEF 


CLIPVIEW. DEF  module  definition  file 


NAME  CLIPVIEW 

DESCRIPTION  'Simple  Clipboard  Viewer  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


CLIPVIEW  processes  WM-CREATE,  WM_CHANGECBCHAIN,  WM-DRAWCLIP- 
BOARD,  and  WM -DESTROY  messages  as  discussed  above.  The  WM -PAINT  message  sim¬ 
ply  opens  the  clipboard  and  uses  GetClipboardData  with  a  format  of  CF-TEXT.  If  the 
function  returns  a  global  memory  handle,  CLIPVIEW  locks  it  and  uses  DrawText  to  display 
the  text  in  its  client  area. 


821 


SECTION  V:  DATA  EXCHANGE  AND  LINKS 


A  clipboard  viewer  that  handles  data  formats  beyond  the  five  standard  formats 
(as  CLIPBRD.EXE  does)  has  additional  work  to  do,  such  as  displaying  the  names  of  all  the 
formats  currently  in  the  clipboard.  You  can  do  this  by  calling  EnumClipboardFormats 
and  obtaining  the  names  of  the  nonstandard  formats  from  GetClipboardFormatName.  A 
clipboard  viewer  that  uses  the  CF_OWNERDISPLAY  format  must  send  these  four  messages 
to  the  clipboard  to  display  the  data: 

WM-PAINTCLIPBOARD  WM_VSCROLLCLIPBOARD 

WM-SIZECLIPBOARD  WM-HSCROLLCLIPBOARD 

If  you  want  to  write  such  a  clipboard  viewer,  you  have  to  obtain  the  window  handle  of  the 
clipboard  owner  using  GetClipboardOwner  and  send  that  window  these  messages  when 
you  need  to  update  the  clipboard  viewer’s  client  area. 
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Dynamic  Data 
Exchange 
(DDE) 


Dynamic  Data  Exchange  (DDE)  is  one  of  three  mechanisms  of  interprocess  communi¬ 
cation  supported  under  Windows.  The  other  two  are  the  Windows  clipboard  (which  I 
discussed  in  Chapter  16)  and  shared  memory  in  dynamic  link  libraries  (Chapter  19). 

DDE  is  based  on  the  messaging  system  built  into  Windows.  Two  Windows  programs 
carry  on  a  DDE  “conversation”  by  posting  messages  to  each  other.  These  two  programs  are 
known  as  the  “server”  and  the  “client.”  A  DDE  server  is  the  program  that  has  access  to  data 
that  may  be  useful  to  other  Windows  programs.  A  DDE  client  is  the  program  that  obtains 
this  data  from  the  server. 

In  Windows  3.1,  programs  can  optionally  use  the  DDE  Management  Library 
(DDEML),  which  simplifies  DDE  in  several  ways.  DDEML  insulates  the  program  from  DDE 
messaging  by  providing  a  high-level  function  call  layer.  Programs  using  DDEML  respond  to 
DDE  messages  using  a  call-back  function.  The  two  methods  of  using  DDE  are  compatible 
because  DDEML  is  built  on  top  of  the  DDE  messaging  system. 

In  this  chapter,  I’ll  first  discuss  the  traditional  approach  to  DDE  and  then  show  how 
the  interprocess-communication  problem  is  solved  using  DDEML. 
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A  DDE  conversation  is  initiated  by  the  client  program.  The  client  broadcasts  a  mes¬ 
sage  (called  WM_DDE_INITIATE)  to  all  currently  running  Windows  programs.  This 
message  indicates  a  general  category  of  data  the  client  needs.  A  DDE  server  that  has  this 
data  can  respond  to  this  broadcasted  message.  At  that  point,  the  conversation  begins. 

A  single  Windows  program  can  be  both  a  client  to  one  program  and  a  server  to  another, 
but  this  requires  two  different  DDE  conversations.  A  server  can  deliver  data  to  multiple  cli¬ 
ents,  and  a  client  can  obtain  data  from  multiple  servers,  but  again,  this  requires  multiple 
DDE  conversations.  To  keep  these  conversations  unique  and  separate,  each  conversation 
(on  both  the  client  and  server  sides)  uses  a  different  window.  Generally,  a  program  that  sup¬ 
ports  DDE  will  create  a  hidden  child  window  for  each  conversation  it  maintains. 

The  programs  involved  in  a  DDE  conversation  need  not  be  specifically  coded  to 
work  with  each  other.  As  I’ll  discuss  in  the  next  section,  generally  the  writer  of  a  DDE 
server  will  publicly  document  how  the  data  is  identified.  A  user  of  a  program  that  can  act  as 
a  DDE  client  (such  as  Microsoft  Excel)  can  use  this  information  to  establish  a  DDE  conver¬ 
sation  between  the  two  programs. 

If  you  write  a  family  of  two  or  more  Windows  programs  that  must  communicate  with 
each  other  but  not  with  other  Windows  programs,  you  may  consider  defining  your  own 
messaging  protocol.  However,  this  is  not  recommended.  While  it  may  work  in  current  ver¬ 
sions  of  Windows,  it  is  possible  that  future  versions  of  Windows  will  not  support  any  form 
of  message-based  interprocess  communication  except  for  DDE. 

Because  DDE  uses  the  messaging  system  built  into  Windows,  it  fits  very  naturally  in 
the  environment.  But  this  is  not  to  say  that  DDE  is  easy  to  implement.  The  protocol  has 
many  options,  and  programs  must  be  ready  to  deal  with  some  rather  tricky  problems. 

BASIC  CONCEPTS 

When  a  client  asks  a  server  for  data,  it  must  be  able  to  identify  the  type  of  data  it  wants.  This  is 
done  with  three  character  strings,  called  the  “application,”  the  data  “topic,”  and  the  data  “item.” 

Application,  Topic,  and  Item 

The  idea  of  the  application,  topic,  and  item  is  best  approached  with  an  example.  In  the  first 
half  of  this  chapter,  I’ll  show  you  how  to  write  a  Windows  DDE  server  program  called 
DDEPOP1.  This  program  contains  population  data  of  the  United  States  from  the  1970, 1980, 
and  1990  censuses.  Based  on  a  quadratic  extrapolation,  the  program  can  calculate  the  in¬ 
stantaneous  (“at  this  moment”)  population  of  any  state  or  of  the  United  States  as  a  whole. 

Anybody  who  writes  a  DDE  server  program  should  document  how  this  data  is  iden¬ 
tified  using  three  character  strings: 

■  The  server  application  name:  In  this  example,  this  is  simply  “DDEPOP1.” 

Each  server  has  only  one  application  name,  the  name  of  the  program. 
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■  The  topic  name:  All  DDE  servers  support  at  least  one  topic.  In  the  case  of 
DDEPOP1,  only  one  topic  is  supported,  which  is  identified  by  the  string 
“US_Population.”  Conceivably,  the  DDEPOP1  program  could  be  expanded 
to  include  data  concerning  the  square-mile  areas  of  the  states,  in  which 
case  the  program  would  support  a  second  topic  named  “US -Area.” 

■  The  item  name:  Within  each  topic,  a  DDE  server  supports  one  or  more 
data  items.  In  DDEPOP1,  the  item  identifies  the  state  using  the  standard 
two-character  post-office  abbreviation,  such  as  “NY”  for  New  York,  “CA” 
for  California,  and  “US”  for  the  total.  DDEPOP1  supports  52  items — the 
50  states,  the  District  of  Columbia  (“DC”),  and  the  total. 

This  documentation  is  sufficient  to  use  the  DDEPOP1  server  with  another  Windows 
program  that  can  act  as  a  client,  for  example,  Microsoft  Excel.  To  use  DDEPOP1  with 
Microsoft  Excel,  you  can  type  the  following  into  a  spreadsheet  cell: 

=DDEP0P1 ! US_Popul ati  on ! US 

These  three  strings  indicate  the  application,  topic,  and  item  (in  this  case,  the  total 
United  States  population).  IfDDEPOPl.EXE  is  not  already  running,  Microsoft  Excel  will  at¬ 
tempt  to  execute  it.  (DDEPOP1  must  be  in  the  current  directory  or  in  a  directory  listed  in 
the  PATH  environment  variable.)  If  successful,  Excel  will  initiate  a  DDE  conversation  with 
DDEPOP1,  obtain  the  population  data,  and  display  the  population  as  a  number  in  the  cell. 
These  population  figures  can  be  formatted,  graphed,  or  used  in  calculations. 

What’s  most  interesting  is  that  the  population  figures  will  be  periodically  updated  in 
the  spreadsheet.  This  is  known  as  a  “hot  link”  or  (in  a  slight  variation)  “warm  link.”  Every  5 
seconds,  DDEPOP1  recalculates  the  population  data  and  notifies  a  client  when  an  item  has 
changed.  In  the  case  of  the  total  U.S.  population,  you’ll  see  the  figure  increase  by  1  about 
every  15  seconds. 

The  Types  of  Conversations 

There  are  three  basic  types  of  DDE  conversations — cold  link,  hot  link,  and  warm  link. 
These  conversations  use  DDE  messages  defined  in  the  DDE.H  header  file.  The  simplest  of 
the  three  conversations  is  known  as  the  cold  link. 

1.  The  Cold  Link 

A  cold  link  conversation  begins  when  a  client  broadcasts  a 
WM_DDE_INITIATE  message  identifying  the  application  and  topic  it 
requires.  (The  application  and  topic  may  be  set  to  NULL  to  begin  a 
conversation  with  any  server  application  or  any  data  topic.)  A  server 
application  that  supports  the  specified  topic  responds  to  the  client  with  a 
WM_DDE_ACK  (“acknowledge”)  message: 
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The  client  then  requests  a  particular  data  item  by  posting  a  WM_DDE- 
-REQUEST  message.  If  the  server  can  supply  this  data  item,  it  responds 
by  posting  a  WM_DDE_DATA  message  to  the  client: 


WM_DDE_REQUEST  w| 

(item) 

Client 

WM  DDE  DATA 

Server 

(item) 

(WM  DDE  ACK) 

w 

(positive) 

I’ve  also  indicated  here  that  the  client  can  acknowledge  to  the  server  that 
it  has  received  the  WM_DDE_DATA  message.  This  is  optional  (which  I’ve 
indicated  by  putting  the  WM_DDE_ACK  message  within  parentheses). 
The  server  indicates  whether  it  wants  this  acknowledgment  in  a  flag 
passed  with  the  WM_DDE_DATA  message.  A  flag  passed  with  the 
WM_DDE_ACK  message  indicates  a  “positive”  acknowledgment. 

If  the  client  posts  a  WM_DDE -REQUEST  message  to  the  server,  and 
the  server  cannot  supply  the  requested  data  item,  then  the  server  posts  a 
“negative”  WM_DDE_ACK  message  to  the  client: 


The  DDE  conversation  continues  with  the  client  posting  WM_DDE- 
_REQUEST  messages  to  the  server — for  the  same  data  item  or  different 
data  items — and  the  server  responding  with  WM_DDE_DATA  or 
WM_DDE_ACK  messages.  The  conversation  is  terminated  when  the 
client  and  server  post  each  other  WM_DDE -TERMINATE  messages: 


- WM_DDE_TERMINATE - > 

< - WM_DDE_TERMINATE - 


Server 


Client 
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Although  I’ve  indicated  that  the  client  posts  the  first  WM_DDE_TER- 
MINATE  message,  this  is  not  always  the  case.  The  server  can  post  the  first 
WM _DDE -TERMINATE  message,  and  the  client  must  respond  to  that. 

2.  The  Hot  Link 

One  problem  with  the  cold  link  is  that  the  data  the  server  has  access 
to  may  change  with  the  passing  of  time.  (This  is  the  case  with  DDEPOP1, 
which  calculates  an  instantaneous  population  that  can  change.)  In  the 
cold  link,  the  client  does  not  know  when  the  data  changes.  The  hot  link 
solves  this  problem. 

Again,  the  DDE  conversation  begins  with  a  WM_DDE_INITIATE 
message  and  a  WM_DDE_ACK  message: 


Client 

WM  DDE  INITIATE 
(application,  topic) 

*  WM  DDF  A  ok 

Server 

The  client  indicates  the  data  item  it  requires  by  posting  a  WM-DDE- 
-ADVISE  message  to  the  server.  The  server  responds  by  posting  a 
WM_DDE_ACK  message  indicating  if  it  has  access  to  this  item: 


A  positive  acknowledgment  indicates  that  the  server  can  supply  the  data; 
a  negative  acknowledgment  indicates  that  it  cannot. 

At  this  point,  the  server  is  obligated  to  notify  the  client  whenever 
the  value  of  the  data  item  changes.  This  notification  uses  a  WM- 
_DDE_DATA  message,  to  which  the  client  (based  on  a  flag  set  in  the 
WM  _DDE -DATA  message)  may  or  may  not  respond  with  a  WM- 
_DDE_ACK  message: 
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When  the  client  no  longer  wishes  to  be  advised  of  updates  to  the  data 
item,  it  posts  a  WM_DDE_UNADVISE  message  to  the  server,  and  the 
server  acknowledges: 


WM  DDE  UNADVISE 

Client 

(item) 

w 

Server 

\a/m  nni=  Ark' 

The  conversation  is  terminated  with  the  posting  of  WM_DDE_TER- 
MINATE  messages: 


- WM_DDE_TERMINATE - > 

< - WM  DDE_TERMINATE - 


Client 


Server 


The  cold  link  and  the  hot  link  are  not  mutually  exclusive.  During  a  single 
DDE  conversation,  a  client  may  ask  for  some  data  items  by  using  WM- 
_DDE_REQUEST  (for  a  cold  link)  and  ask  for  others  by  using  WM_DDE- 
_ADVISE  (for  a  hot  link). 

3.  The  Warm  Link 

The  warm  link  combines  elements  of  the  cold  link  and  hot  link.  The 
conversation  begins  as  normal: 


As  with  the  hot  link,  the  client  posts  a  WM_DDE_ADVISE  message  to  the 
server,  and  the  server  acknowledges  either  positively  or  negatively: 
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However,  a  flag  passed  with  the  WM _DDE -  ADVISE  message  indicates 
that  the  client  wishes  only  to  be  informed  of  changes  in  data  without 
immediately  receiving  the  new  data  item.  So  the  server  posts  WM- 
_DDE_DATA  messages  with  NULL  data: 


WM_DDE_DATA 
(NULL  item) 

WM_DDE_ACK - > 


Server 


Client 


Now  the  client  knows  that  a  particular  data  item  has  changed.  To  obtain 
this  item,  the  client  uses  a  WM_DDE -REQUEST  message,  just  as  in  the 
cold  link: 


As  in  the  hot  link,  a  client  can  stop  being  advised  of  changes  in  data  items 
by  posting  a  WM_DDE_UNADVISE  message  to  the  server: 


The  conversation  is  terminated  with  the  WM_DDE -TERMINATE 
messages: 


WM  nnF  TFRMINATF  ^ 

Client 

Server 

< - WM_DDE_TERMINATE - 

These  three  types  of  conversations  use  all  the  DDE  messages  except  two: 
WM_DDE_POKE  (in  which  a  client  gives  a  server  unsolicited  data)  and  WM_DDE- 
-EXECUTE  (in  which  a  client  sends  a  command  string  to  a  server).  I  won’t  be  covering 
these  messages  in  this  chapter. 
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The  DDE.H  header  file  also  defines  four  structures: 

■  DDEACK  (used  in  the  WM_DDE_ACK  message) 

■  DDEADVISE  (used  in  the  WM_DDE_ADVISE  message) 

■  DDEDATA  (used  in  the  WM_DDE_DATA  message) 

■  DDEPOKE  (used  in  the  WM_DDE_POKE  message) 

I’ll  deal  with  the  first  three  structures  as  I  discuss  the  sample  programs  in  this  chapter. 

Character  Strings  and  Atoms 

I’ve  discussed  how  a  DDE  client  and  server  identify  data  using  three  character  strings — 
the  application,  topic,  and  item.  But  in  the  actual  messages  between  the  client  and  server, 
these  character  strings  do  not  appear:  “Atoms”  are  used  instead. 

Atoms  are  WORD  values  that  refer  to  character  strings  in  a  case-insensitive  manner. 
You  can  use  atoms  within  your  own  program  for  working  with  character  strings,  in  which 
case  the  atom  table  (the  table  that  references  the  atom  values  with  the  strings)  is  stored  in 
your  program’s  default  data  segment. 

You  define  an  atom  as  follows: 

ATOM  aAtom  ; 

You  can  add  a  string  to  the  atom  table  using  the  function: 
aAtom  =  AddAtom  ClpString)  ; 

If  the  character  string  does  not  already  exist  in  the  atom  table,  this  function  adds  it  and 
returns  a  unique  value  identifying  the  string.  Each  atom  has  a  “reference  count,”  which  is 
the  number  of  times  AddAtom  has  been  called  for  the  same  string.  The  reference  count  is 
initially  set  to  1.  If  the  character  string  already  exists  in  the  atom  table  (that  is,  if  this  is  the 
second  or  subsequent  time  that  AddAtom  has  been  called  for  the  same  string),  the  function 
returns  the  number  identifying  the  character  string  and  increments  the  reference  count. 
The  function: 

DeleteAtom  (aAtom)  ; 

decrements  the  reference  count.  When  the  count  is  0,  the  atom  and  character  string  are 
removed  from  the  atom  table. 

The  function: 

aAtom  =  FindAtom  (IpString)  ; 

will  return  the  atom  associated  with  the  character  string  (or  0  if  the  string  is  not  in  the  atom 
table).  This  function  does  not  affect  the  reference  count  of  the  atom. 

The  function: 

nBytes  =  GetAtomName  (aAtom,  lpBuffer,  nBufferSize)  ; 
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returns  the  character  string  for  an  atom.  The  last  parameter  indicates  the  size  of  the  buffer 
pointed  to  by  the  second  parameter.  The  function  returns  the  number  of  bytes  copied  to 
the  buffer  and  does  not  affect  the  reference  count. 

These  four  functions  (there  are  several  others  of  lesser  importance)  allow  you  to  work 
with  atoms  within  your  own  program.  However,  because  the  atom  table  is  stored  in  your  pro¬ 
gram’s  default  data  segment,  the  atoms  are  unique  to  your  program.  To  use  atoms  with  DDE, 
you  must  use  another  set  of  four  functions,  similar  to  the  functions  described  above: 

aAtom  =  Global AddAtom  (IpString)  ; 

Global  Del eteAtom  (aAtom)  ; 

aAtom  =  Global FindAtom  (IpString)  ; 

nBytes  =  G1 obal GetAtomName  (aAtom,  lpBuffer,  nBufferSize)  ; 

The  atom  table  for  these  atoms  is  stored  in  a  shared  data  segment  in  a  dynamic  link 
library  within  Windows  and  hence  is  common  to  all  Windows  programs.  One  program 
can  use  GlobalAddAtom  to  add  a  string  to  the  atom  table  and  pass  the  atom  to  another 
program.  This  other  program  can  use  GlobalGetAtomName  to  obtain  the  character  string 
associated  with  the  atom.  This  is  how  Windows  programs  identify  the  DDE  application, 
topic,  and  item. 

The  rules  regarding  the  use  of  atoms  with  DDE  are  extremely  important:  It  is  not  good  if 
an  atom  that  is  still  required  by  one  program  is  deleted  from  the  atom  table  by  another  pro¬ 
gram.  Neither  is  it  good  if  atoms  that  are  no  longer  required  are  not  deleted  from  the  atom 
table.  For  this  reason,  you  must  be  careful  about  how  your  program  handles  atoms. 

Atoms  are  used  for  the  DDE  application,  topic,  and  item  strings.  The  data  structures 
that  are  transferred  from  one  Windows  program  to  another  must  be  allocated  using 
GlobalAlloc  with  the  GMEM_DDESHARE  option.  This  allows  the  global  memory  block  to 
be  shared  among  multiple  Windows  programs.  The  DDE  rules  that  govern  which  program 
is  responsible  for  allocating  and  freeing  these  global  memory  blocks  are  also  quite  strict. 


A  DDE  SERVER  PROGRAM 

We  are  now  ready  to  begin  looking  at  DDEPOP1,  the  DDE  server  program  that  can  supply 
instantaneous  state  population  data  to  a  DDE  client.  This  program  is  shown  in  Figure  17-1. 

DDEPOP1  -MAK 

# - - 

#  DDEP0P1.MAK  make  file 
#--- . - . . 

ddepopl.exe  :  ddepopl. obj  ddepopl.def  ddepopl.res 

$(WINLINK)  ddepopl,  ddepopl,  NUL,  $(WINLIB),  ddepopl 
rc  -t  ddepopl.res 

Figure  17-1 .  The  DDEPOP1.MAK program .  (continued) 
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ddepopl.obj  :  ddepopl.c  ddepop.h 
$ ( W I NCC )  ddepopl.c 

ddepopl.res  :  ddepopl.rc  ddepop.ico 
$ ( W I N RC )  ddepopl.rc 


DDEPOP1.C 


/* - - - 

DDEP0P1 . C  --  DDE  Server  for  Population  Data 
(c)  Charles  Petzold,  1992 
. . . . . . . */ 

#i  ncl ude  <windows.h> 

#i ncl ude  <dde.h> 

#i ncl ude  <string.h> 

#i  ncl ude  "ddepop.h” 

typedef  struct 
{ 

unsigned  int  f Advi se : 1  ; 
unsigned  int  f Def erllpd :  1  ; 
unsigned  int  f AckReq : 1  ; 
unsigned  int  dummy:13  ; 
long  IPopPrev  ; 

} 

POPADVISE  ; 

#define  I D_T I M E R  1 
#define  DDE_T I MEOUT  3000 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

long  FAR  PASCAL  .export  ServerProc  (HWND,  UINT,  UINT.  LONG)  ; 

BOOL  FAR  PASCAL  .export  TimerEnumProc  (HWND,  LONG)  ; 

BOOL  FAR  PASCAL  .export  Cl oseEnumProc  (HWND,  LONG)  ; 

BOOL  PostDataMessage  (HWND,  HWND,  int,  BOOL,  BOOL.  BOOL)  ; 

char  szAppName  []  =  "DdePopl"  ; 

char  szServerClass  []  =  "DdePopl .Server"  ; 

HANDLE  hlnst  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  (hPrevInstance) 


(continued) 
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return  FALSE  ; 


hlnst  =  hlnstance  ; 


//  Register  window  class 


wndclass 
wndcl ass 
wndclass 
wndclass 
wndclass 
wndclass 
wndclass 
wndclass 
wndclass 
wndclass 


.style 

.lpfnWndProc 

.cbClsExtra 

.cbWndExtra 

.hlnstance 

.hlcon 

.hCursor 

.hbrBackground 

.1 pszMenuName 

.lpszClassName 


WndProc 


hlnstance  ; 

Loadlcon  (hlnstance,  szAppName) 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITE_BRUSH)  ; 
NULL  ; 
szAppName  ; 


RegisterClass  Uwndclass)  ; 


//  Register  window  class  for  DDE  Server 


wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass. 

wndclass, 

wndclass, 

wndclass, 


style 

lpfnWndProc 

cbClsExtra 

cbWndExtra 

hlnstance 

hlcon 

hCursor 

hbrBackground 

1 pszMenuName 

lpszClassName 


ServerProc  ; 

0  ; 

2  *  sizeof  (WORD) 
hlnstance  ; 

NULL 
NULL 
NULL 
NULL 

szServerClass 


RegisterClass  (&wndclass) 


hwnd  =  CreateWindow  (szAppName,  "DDE  Population  Server", 
WS_OVERLAPP EDWIN DOW , 

CWJJSEDEFAULT,  CW_US EDE FAU LT , 
CWJJSEDEFAULT,  CWJJSEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 


InitPops  0  ;  //  initialize  'pop'  structure 

if  USetTimer  (hwnd,  I D_T I M E R ,  5000,  NULL)) 

{ 

MessageBox  (hwnd,  "Too  many  clocks  or  timers!",  szAppName, 
MB.ICONEXCLAMATION  !  MB_0K)  ; 


return  FALSE  ; 

} 

ShowWindow  (hwnd,  SW_SH0WMI NNOACTI VE )  ; 
UpdateWindow  (hwnd)  ; 


( continued ) 
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while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  ( &msg )  ; 

DispatchMessage  (&msg)  ; 

} 

Kill  Timer  (hwnd,  ID.TIMER)  ; 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  FARPROC  1 pTimerEnumProc,  1 pCl oseEnumProc  ; 

static  char  szTopic  []  =  "US.Population"  ; 

ATOM  aApp,  aTop  ; 

HWND  hwndClient,  hwndServer  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

IpTimerEnumProc  =  MakeProcInstance  ((FARPROC)  TimerEnumProc, 

hlnst)  ; 

lpCloseEnumProc  =  MakeProcInstance  ((FARPROC)  CloseEnumProc, 

hlnst)  ; 

return  0  ; 

case  WM_DDE_INITIATE  : 

//  wParam  --  sending  window  handle 

.  //  LOWORD  (IParam)  --  application  atom 

//  HIWORD  (IParam)  --  topic  atom 

hwndClient  =  wParam  ; 

aApp  =  GlobalAddAtom  (szAppName)  ; 
aTop  =  GlobalAddAtom  (szTopic)  ; 

//  Check  for  matching  atoms,  create  window,  and  acknowledge 

if  ((LOWORD  (IParam)  ==  NULL  !!  LOWORD  (IParam)  ==  aApp)  && 
(HIWORD  (IParam)  ==  NULL  !!  HIWORD  (IParam)  ==  aTop)) 

{ 

hwndServer  =  CreateWindow  (szServerClass,  NULL, 

WS.CHILD,  0,  0,  0,  0, 
hwnd,  NULL,  hlnst,  NULL)  ; 


(continued) 
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SetWindowWord  (hwndServer,  0,  hwndClient)  ; 
SendMessage  (wParam,  WM_DDE_ACK,  hwndServer, 

MAKELONG  (aApp,  aTop))  ; 

} 

//  Otherwise,  delete  the  atoms  just  created 

else 

{ 

Global  Del eteAtom  (aApp)  ; 

Global  Del eteAtom  (aTop)  ; 

} 

return  0  ; 

case  WM_TIMER  : 
case  WM_TIMECHANGE  : 

//  Calculate  new  current  populations 

CalcPops  0  ; 

//  Notify  all  child  windows 

EnumChildWindows  (hwnd,  lpTimerEnumProc,  0L)  ; 
return  0  ; 

case  WM.QUERYOPEN  : 
return  0  ; 

case  WM_CL0SE  : 

//  Notify  all  child  windows 

EnumChildWindows  (hwnd,  IpCloseEnumProc,  0L)  ; 

break  ;  //  for  default  processing 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

long  FAR  PASCAL  _export  ServerProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

ATOM  altem  ; 

char  szltem  [10]  ; 


(continued) 
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DDEACK  DdeAck  ; 

DDEADVISE  FAR  *1 pDdeAdvi se  ; 

DWORD  dwTime  ; 

GLOBALHANDLE  hPopAdvise,  hDdeAdvise,  hCommands,  hDdePoke  ; 
int  ’  i  ; 

HWND  hwndCl lent  ; 

MSG  msg  ; 

POPADVISE  FAR  *1 pPopAdvi se  ; 

WORD  cfFormat,  wStatus  ; 

switch  (message) 

{ 

case  WM_CREATE  : 

//  Allocate  memory  for  POPADVISE  structures 

hPopAdvise  =  GlobalAlloc  (GHND,  NUM.STATES  *  sizeof  (POPADVISE))  ; 

if  (hPopAdvise  ==  NULL) 

DestroyWindow  (hwnd)  ; 

el  se 

SetWindowWord  (hwnd,  2,  hPopAdvise)  ; 
return  0  ; 

case  WM_DDE_REQUEST  : 

//  wParam  --  sending  window  handle 

//  LOWORD  (IParam)  --  data  format 
//  HIWORD  (IParam)  --  item  atom 

hwndClient  =  wParam  ; 
cfFormat  =  LOWORD  (IParam)  ; 
a  Item  =  HIWORD  (IParam)  ; 

//  Check  for  matching  format  and  data  item 

if  (cfFormat  ==  C F_T EXT) 

{ 

Global GetAtomName  (altem,  szltem,  sizeof  (szltem))  ; 

for  (i  =  0  ;  i  <  NUM_STATES  ;  1++) 

if  (strcmp  (szltem,  pop[i ] .szState)  ==  0) 
break  ; 

if  (i  <  NUM_STATES) 

{ 

GlobalDeleteAtom  (altem)  ; 

PostDataMessage  (hwnd,  hwndClient,  i, 

FALSE,  FALSE,  TRUE)  ; 


(continued) 
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return  0  ; 

} 

} 

//  Negative  acknowledge  if  no  natch 

DdeAck. bAppReturnCode  =  0  ; 

DdeAck. reserved  =  0  ; 

DdeAck. fBusy  =  FALSE  ; 

DdeAck. fAck  =  FALSE  ; 

wStatus  =  *  (WORD  *)  &  DdeAck  ; 

if  ( IPostMessage  (hwndClient,  WM_DDE_ACK,  hwnd, 

MAKELONG  (wStatus,  altem))) 

{ 

Global  Del eteAtom  (altem)  ; 

} 

return  0  ; 

case  WM_DDE_ADVISE  : 

//  wParam  --  sending  window  handle 

//  LOWORD  (1 Param)  --  DDEADVISE  memory  handle 
//  HIWORD  (IParam)  --  item  atom 

hwndClient  =  wParam  ; 

hDdeAdvise  =  LOWORD  (IParam)  ; 

altem  =  HIWORD  (IParam)  ; 

lpDdeAdvise  =  (DDEADVISE  FAR  *)  Global  Lock  (hDdeAdvise)  ; 

//  Check  for  matching  format  and  data  item 

if  (lpDdeAdvise->cf Format  ==  CF.TEXT) 

{ 

Global GetAtomName  (altem,  szltem,  sizeof  (szltem))  ; 

for  (1  =  0  ;  1  <  NUM_STATES  ;  i++) 

if  (strcmp  (szltem,  pop[i ] . szState)  ==  0) 
break  ; 

//  Fill  in  the  POPADVISE  structure  and  acknowledge 

if  (i  <  NUM_STATES) 

{ 

hPopAdvise  =  GetWindowWord  (hwnd,  2)  ; 

IpPopAdvise  =  (POPADVISE  FAR  *) 

Global  Lock  (hPopAdvise)  ; 


(continued) 
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lpPopAdvise[i].f Advise  =  TRUE  ; 

1 pPopAdvi se[i ] . f DeferUpd  =  lpDdeAdvise->fDeferUpd  ; 
1 pPopAdvi se[i ] . f AckReq  =  lpDdeAdvise->fAckReq  ; 

1 pPopAdvi se[i].lPopPrev  =  pop [i ] . 1  Pop  ; 

GlobalUnlock  (hDdeAdvise)  ; 

G1 obal Free  (hDdeAdvise)  ; 

DdeAck.bAppReturnCode  =  0  ; 

DdeAck. reserved  =  0  ; 

DdeAck.fBusy  =  FALSE  ; 

DdeAck. fAck  =  TRUE  ; 

wStatus  =  *  (WORD  *)  &  DdeAck  ; 

if  ( ! PostMessage  (hwndClient,  WM_DDE_ACK,  hwnd, 
MAKELONG  (wStatus,  altem))) 

{ 

Global  Del eteAtom  (altem)  ; 

} 

else 

{ 

PostDataMessage  (hwnd,  hwndClient,  i, 

1 pPopAdvi se[i ] . fDeferUpd , 

1 pPopAdvi se[i ] . f AckReq , 

FALSE)  ; 

} 

GlobalUnlock  (hPopAdvise)  ; 
return  0  ; 

} 


//  Otherwise  post  a  negative  WM_DDE_ACK 

GlobalUnlock  (hDdeAdvise)  ; 

DdeAck.bAppReturnCode  =  0  ; 

DdeAck. reserved  =  0  ; 

DdeAck.fBusy  =  FALSE  ; 

DdeAck. fAck  =  FALSE  ; 

wStatus  =  *  (WORD  *)  &  DdeAck  ; 

if  ( IPostMessage  (hwndClient,  WM_DDE_ACK,  hwnd, 
MAKELONG  (wStatus,  altem))) 

{ 

GlobalFree  (hDdeAdvise)  ; 

GlobalDeleteAtom  (altem)  ; 

} 


(continued) 
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return  0  ; 

case  WM_DDE_UNADVISE  : 

//  wParam  --  sending  window  handle 

//  LOWORD  ( 1  Pa  ram)  --  data  format 
//  HIWORD  (IParam)  --  item  atom 

hwndClient  =  wParam  ; 

cf Format  =  LOWORD  (IParam)  ; 

altem  =  HIWORD  (IParam)  ; 

DdeAck.bAppReturnCode  =  0  ; 

DdeAck. reserved  =  0  ; 

DdeAck.fBusy  =  FALSE  ; 

DdeAck. fAck  =  TRUE  ; 

hPopAdvise  =  GetWindowWord  (hwnd,  2)  ; 

IpPopAdvise  =  (POPADVISE  FAR  *)  GlobalLock  (hPopAdvise)  ; 

//  Check  for  matching  format  and  data  item 

if  (cfFormat  ==  CF_TEXT  ii  cfFormat  ==  0) 

{ 

if  (altem  ==  NULL) 

for  (i  =  0  ;  i  <  NUM_STATES  ;  i++) 

1 pPopAdvi se[i ] . f Advi se  =  FALSE  ; 

else 

{ 

Global GetAtomName  (altem,  szltem,  sizeof  (szltem))  ; 

for  (i  =  0  ;  i  <  NUM_STATES  ;  i++) 

if  (strcmp  (szltem,  pop[i ] .szState)  ==  0) 
break  ; 

if  (i  <  NUM_STATES) 

1 pPopAdvi se[i ] . f Advi se  =  FALSE  ; 

else 

DdeAck. fAck  =  FALSE  ; 

} 

} 

else 

DdeAck. fAck  =  FALSE  ; 

//  Acknowledge  either  positively  or  negatively 

wStatus  =  *  (WORD  *)  &  DdeAck  ; 

if  ( IPostMessage  (hwndClient,  WM_DDE_ACK,  hwnd, 

MAKELONG  (wStatus,  altem))) 

{ 


(continued) 
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if  (altem  !=  NULL) 

Global  Del eteAtom  (altem)  ; 

} 

GlobalUnlock  (hPopAdvise)  ; 
return  0  ; 

case  WM_DDE_EXECUTE  : 

//  Post  negative  acknowledge 

hwndClient  =  wParam  ; 
hCommands  =  HIWORD  (IParam)  ; 

DdeAck.bAppReturnCode  =  0  ; 

DdeAck. reserved  =  0  ; 

DdeAck.fBusy  =  FALSE  ; 

DdeAck. fAck  =  FALSE  ; 

wStatus  =  *  (WORD  *)  &  DdeAck  ; 

if  (IPostMessage  (hwndClient,  WM_DDE_ACK,  hwnd, 
MAKELONG  (wStatus,  hCommands))) 

{ 

GlobalFree  (hCommands)  ; 

} 

return  0  ; 

case  WM_DDE_POKE  : 

//  Post  negative  acknowledge 

hwndClient  =  wParam  ; 
hDdePoke  =  LOWORD  (IParam)  ; 
altem  =  HIWORD  (IParam)  ; 

DdeAck.bAppReturnCode  =  0  ; 

DdeAck. reserved  =  0  ; 

DdeAck.fBusy  =  FALSE  ; 

DdeAck. fAck  =  FALSE  ; 

wStatus  =  *  (WORD  *)  &  DdeAck  ; 

if  (IPostMessage  (hwndClient,  WM_DDE_ACK,  hwnd, 
MAKELONG  (wStatus,  altem))) 

{ 

GlobalFree  (hDdePoke)  ; 

Global  Del eteAtom  (altem)  ; 

} 

return  0  ; 
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case  WM_D D E_T E RM I N AT E  : 

//  Respond  with  another  WM_DDE_TERMINATE  message 
hwndClient  =  wParam  ; 

PostMessage  (hwndClient.  WM_DDE_TERMINATE.  hwnd,  0L)  ; 

DestroyWindow  (hwnd)  ; 
return  0  ; 

case  WM_TIMER  : 

//  Post  WM_DDE_DATA  messages  for  changed  populations 

hwndClient  =  GetWindowWord  (hwnd,  0)  ; 
hPopAdvise  =  GetWindowWord  (hwnd,  2)  ; 

IpPopAdvise  =  (POPADVISE  FAR  *)  Global  Lock  (hPopAdvise)  ; 

for  (i  =  0  ;  i  <  NUM.STATES  ;  i++) 
if  ( 1 pPopAdvi se[i ] . f Advi se ) 

if  ( 1 pPopAdvi se[i ] . 1 PopPrev  !=  pop[i ] . 1  Pop) 

{ 

if  ( IPostDataMessage  (hwnd,  hwndClient,  i, 

1 pPopAdvi s  e [ i ] . fDeferUpd , 

1 pPopAdvi se[i ] . f AckReq , 

FALSE)) 

break  ; 

1 pPopAdvi se[i ] *  1 PopPrev  =  pop[i ] . 1  Pop  ; 

} 

G1 obal Unlock  (hPopAdvise)  ; 
return  0  ; 

case  WM_CL0SE  : 

//  Post  a  WM_DDE_TERMI NATE  message  to  the  client 

hwndClient  =  GetWindowWord  (hwnd,  0)  ; 

PostMessage  (hwndClient,  WM_DDE_TERMI NATE ,  hwnd,  0L)  ; 

dwTime  =  GetCurrentTime  0  ; 

while  (GetCurrentTime  0  -  dwTime  <  DDE_TIMEOUT) 
if  (PeekMessage  (&msg,  hwnd,  WM_DDE_TERMINATE, 

WM_D DETERMINATE,  PM.REMOVE)) 

break  ; 

DestroyWindow  (hwnd)  ; 
return  0  ; 

(continued) 
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case  WM.DESTROY  : 

hPopAdvise  =  GetWindowWord  (hwnd,  2)  ; 

GlobalFree  (hPopAdvise)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

BOOL  FAR  PASCAL  .export  TimerEnumProc  ( HWND  hwnd,  LONG  IParam) 

{ 

SendMessage  (hwnd,  WM.TIMER,  0,  0L)  ; 

return  TRUE  ; 

} 

BOOL  FAR  PASCAL  .export  Cl oseEnumProc  (HWND  hwnd,  LONG  IParam) 

{ 

SendMessage  (hwnd,  WM.CLOSE,  0,  0L)  ; 

return  TRUE  ; 

} 

BOOL  PostDataMessage  (HWND  hwndServer,  HWND  hwndClient,  int  iState, 

BOOL  fDeferUpd,  BOOL  fAckReq,  BOOL  fResponse) 

{ 

ATOM  altem  ; 

char  szPopulation  [16]  ; 

DDEACK  DdeAck  ; 

DDEDATA  FAR  *1 pDdeData  ; 

DWORD  dwTime  ; 

GLOBALHANDLE  hDdeData  ; 

MSG  msg  ; 

WORD  wStatus  ; 

altem  =  GlobalAddAtom  ( pop[i State] .szState)  ; 

//  Allocate  a  DDEDATA  structure  if  not  deferred  update 

if  (fDeferUpd) 

{ 

hDdeData  =  NULL  ; 

} 

else 

{ 

wsprintf  (szPopulation,  "%ld\r\n",  pop[i State] . 1  Pop )  ; 

hDdeData  =  GlobalAlloc  (GHND  !  GMEM.DDESHARE, 

sizeof  (DDEDATA)  +  strlen  (szPopulation))  ; 

1 pDdeData  =  (DDEDATA  FAR  *)  Global  Lock  (hDdeData)  ; 
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lpDdeData->fResponse  =  fResponse  ; 
lpDdeData->fRelease  =  TRUE  ; 
lpDdeData->fAckReq  =  fAckReq  ; 
lpDdeData->cf Format  =  CF_TEXT  ; 

lstrcpy  ( ( LPSTR)  1 pDdeData - >Va1 ue,  szPopul ation)  ; 

G1 obal Unlock  (hDdeData)  ; 

} 

//  Post  the  WM_DDE_DATA  message 

if  ( IPostMessage  (hwndClient,  WM_DDE_DATA,  hwndServer, 

MAKELONG  (hDdeData,  altem))) 

{ 

if  (hDdeData  !=  NULL) 

Global  Free  (hDdeData)  ; 

Global  Del eteAtom  (altem)  ; 
return  FALSE  ; 

} 

//  Wait  for  the  acknowledge  message  if  it’s  requested 

if  (fAckReq) 

{ 

DdeAck.fAck  =  FALSE  ; 

dwTime  =  GetCurrentTime  0  ; 

while  (GetCurrentTime  0  -  dwTime  <  DDE_TIMEOUT) 

{ 

if  (PeekMessage  (&msg,  hwndServer,  WM_DDE_ACK,  WM_DDE_ACK, 
PM_REM0VE) ) 

{ 

wStatus  =  LOWORD  (msg.lParam)  ; 

DdeAck  =  *  (DDEACK  *)  &  wStatus  ; 
altem  =  HIWORD  (msg.lParam)  ; 

Global  Del eteAtom  (altem)  ; 
break  ; 

} 

} 

if  (DdeAck.fAck  ==  FALSE) 

{ 

if  (hDdeData  !=  NULL) 

GlobalFree  (hDdeData)  ; 

return  FALSE  ; 

} 

}  • 

return  TRUE  ; 

} 
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DDEPOP.H 

/* . . . — . 

DDEPOP.H  header  file 

Data  from  "The  World  Almanac  and  Book  of  Facts  1992,"  page  75 

. */ 

#i ncl ude  <time.h> 

struct 

{ 

char  *szState  ; 
long  lPop70  ; 

long  lPop80  ; 

long  1 Pop90  ; 

long  IPop  ; 

long  1 PopLast  ; 

long  double  a  ; 
long  double  b  ; 
long  double  c  ; 

} 


"AL", 

3444354, 

3894025, 

4040587, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"AK". 

302583, 

401851, 

550043, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"AZ", 

1775399, 

2716546, 

3665228, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"AR", 

1923322, 

2286357, 

2350725, 

0, 

0, 

0 

0, 

0. 

0. 

0 

.0, 

"CA", 

19971069, 

23667764, 

29760021, 

0. 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"CO", 

2209596, 

2889735, 

3294394, 

0. 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"CT", 

3032217, 

3107564, 

3287116, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0. 

"DE”, 

548104, 

594338, 

666168, 

0, 

0, 

0 

0. 

0. 

0, 

0 

.0. 

"DC", 

756668, 

638432, 

606900, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0. 

"FL", 

6791418, 

9746961, 

12937926, 

0. 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"GA", 

4587930, 

5462982, 

6478216, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"HI", 

769913, 

964691, 

1108229, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0. 

"ID", 

713015, 

944127, 

1006749, 

0, 

0. 

0 

0. 

0. 

0, 

0 

.0, 

"IL", 

11110285, 

11427409, 

11430602, 

0, 

0, 

0 

0. 

0. 

0, 

0 

.0. 

"IN", 

5195392, 

5490214, 

5544159, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"IA", 

2825368, 

2913808, 

2776755, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"KS", 

2249071, 

2364236, 

2477574, 

0, 

0, 

0 

0, 

0. 

0. 

0 

.0, 

"KY", 

3220711, 

3660324, 

3685296, 

0. 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"LA", 

3644637, 

4206116, 

4219973, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"ME", 

993722, 

1125043, 

1227928, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"MD", 

3923897, 

4216933, 

4781468, 

0, 

0, 

0 

0. 

0. 

0, 

0 

.0, 

"MA", 

5689170, 

5737093, 

6016425, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"MI", 

8881826, 

9262044, 

9295297, 

0, 

0, 

0 

0, 

0. 

0, 

0 

.0, 

"MN". 

3806103, 

4075970, 

4375099, 

0, 

0, 

0 

0, 

0. 

0. 

0 

.0, 

"MS", 

2216994, 

2520770, 

2573216, 

0, 

0. 

0 

0, 

0. 

0, 

0 

.0, 

"MO", 

4677623, 

4916766, 

5117073, 

0, 

0, 

0 

0. 

0. 

0, 

0 

.0, 

"MT". 

694409, 

786690, 

799065, 

0, 

0, 

0 

0. 

0. 

0, 

0 

.0. 

"NE", 

1485333, 

1569825, 

1578385, 

0. 

0. 

0 

0, 

0. 

0, 

0 

.0, 
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NV". 

488738, 

800508, 

1201833, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

NH", 

737681, 

920610, 

1109252, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

NJ". 

7171112, 

7365011, 

7730188, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

NM", 

1017055, 

1303302, 

1515069, 

0, 

0, 

0 

0, 

0 

0, 

0 

0. 

NY", 

18241391, 

17558165, 

17990455, 

0. 

0, 

0 

0. 

0 

0, 

0 

0. 

NC", 

5084411, 

5880095, 

6628637, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

ND”, 

617792, 

652717, 

638800, 

0, 

0. 

0 

0, 

0 

0, 

0 

0, 

OH”, 

10657423, 

10797603, 

10847115, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

OK”, 

2559463, 

3025487, 

3145585, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

OR", 

2091533, 

2633156, 

2842321, 

0, 

0, 

0 

0. 

0 

0, 

0 

0, 

PA”, 

11800766, 

11864720, 

11881643, 

0, 

0, 

0 

0. 

0 

0, 

0 

0, 

RI", 

949723, 

947154, 

1003464, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

’SC", 

2590713, 

3120729, 

3486703, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

’SD", 

666257, 

690768, 

696004, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

TN", 

3926018, 

4591023, 

4877185, 

0. 

0, 

0 

0. 

0 

0, 

0 

0, 

TX”, 

11198655, 

14225513, 

16986510, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

’UT", 

1059273, 

1461037, 

1722850, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

’VT”, 

444732, 

511456, 

562758, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

’VA", 

4651448, 

5346797, 

6187358, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

’WA", 

3413244, 

4132353, 

4866692, 

0. 

0, 

0 

0, 

0 

0, 

0 

0, 

’WV", 

1744237, 

1950186, 

1793477, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

’MI". 

4417821, 

4705642, 

4891769, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

’WY”, 

332416, 

469557, 

453588, 

0, 

0, 

0 

0, 

0 

0, 

0 

0, 

’US", 

203302031, 

226542203, 

248709873, 

0, 

0, 

0 

0, 

0 

0, 

0 

0 

}  ; 

#define  NUM_STATES  (sizeof  (pop)  /  sizeof  (pop  [0])) 

void  CalcPops  (void) 

{ 

int  i  ; 
time_t  ITime  ; 

time  (&1 Time)  ;  //  time  in  seconds  since  1/1/70 

#if  _MSC_VER  >=  700 

ITime  -=  (70UL  *  365  +  17)  *  24  *  60  *  60  ; 

#endif 

ITime  -=  92L  *  24  *  60  *  60  ;  //  time  in  seconds  since  4/1/70 

for  (i  =  0  ;  1  <  NUM.STATES  ;  i++) 

popEi ] . 1  Pop  =  (long)  (pop[i].a  *  ITime  *  ITime  + 
pop[i ] . b  *  ITime  + 
pop [ i ] .c)  ; 


void  InitPops  (void) 
{ 

int  i  ; 
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long  double  ldSec80,  ldSec90  ; 

ldSec80  =  3653.0  *  24  *  60  *  60  ;  //  seconds  from  4/1/70  to  4/1/80 

ldSec90  =  7305.0  *  24  *  60  *  60  ;  //  seconds  from  4/1/70  to  4/1/90 

for  (i  =  0  ;  1  <  NUM_STATES  ;  i++) 

{ 

pop[i].a  =  (ldSec90  *  (pop[i].lPop80  ■  pop[i].lPop70)  + 
ldSec80  *  (pop[i].lPop70  -  pop[i].lPop90))  / 

(ldSec90  *  ldSec80  *  (ldSec80  -  1 dSec90) )  ; 

pop[i].b  =  (ldSec90  *  ldSec90  *  (pop[i ] . 1 Pop70  -  pop[i ] .1 Pop80)  + 

ldSec80  *  ldSec80  *  (pop[i].lPop90  -  pop[i].lPop70))  / 

(ldSec90  *  ldSec80  *  (ldSec80  -  ldSec90) )  ; 

pop[i].c  =  pop[i].lPop70  ; 

} 

CalcPops  0  ; 

} 


DDEPOP1.RC 

/* . 

DDEP0P1 . RC  resource  script 


DdePopl  ICON  ddepop.ico 

DDEPOP1.ICO 


DDEPOP1.DEF 


DDEP0P1 . DEF  module  definition  file 


NAME  DDEP0P1 
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DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'DDE  Server  for  Population  Data  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


I  described  earlier  how  you  can  use  this  server  with  Microsoft  Excel.  Later  in  this  chapter 
I’ll  show  you  a  DDE  client  program  (called  SHOWPOP1)  that  also  uses  DDEPOP1  as  a  server. 

The  DDEPOP1  Program 

You’ll  notice  that  the  top  of  the  DDEPOP1.C  listing  contains  the  line: 

^include  <dde.h> 

This  is  the  header  file  that  includes  the  DDE  messages  and  data  structures. 

The  program  then  defines  a  structure  (called  POPADVISE)  using  a  typedef  statement. 
I’ll  discuss  later  how  this  structure  is  used. 

In  WinMain,  the  program  terminates  if  hPrevInstance  is  not  equal  to  NULL.  There  is 
no  reason  for  multiple  copies  of  DDEPOP1  to  be  running  under  Windows.  The  program 
registers  two  window  classes.  The  first  has  the  class  name  “DdePopl”  and  is  used  for  the 
program’s  main  window.  The  second  has  the  class  name  “DdePopl. Server.”  This  second 
class  is  used  for  the  child  windows  that  are  created  to  maintain  multiple  DDE  conversa¬ 
tions.  Each  conversation  requires  its  own  child  window  based  on  this  window  class. 

In  this  second  window  class,  the  cbWndExtra  field  of  the  WNDCLASS  structure  is  set 
to  hold  two  words  per  window.  As  you’ll  see,  the  first  will  be  used  to  store  the  window 
handle  of  the  client  that  the  server  window  is  communicating  with.  The  second  will  be  a 
handle  to  a  global  memory  block  that  contains  NUM -STATE  structures  of  type  POPADVISE. 

After  DDEPOP1  creates  its  main  window,  it  calls  InitPops.  This  function  is  located  in 
DDEPOP.H,  along  with  the  actual  population  data  and  a  function  called  CalcPops  to  calcu¬ 
late  the  instantaneous  populations.  DDEPOP1  also  calls  SetTimer  to  set  a  5-second  timer 
to  periodically  update  the  IPop  field  of  the  pop  structure  in  DDEPOP.H. 

You’ll  notice  that  ShowWindow  is  called  with  the  SW_SHOWMINNOACTIVE 
parameter  and  that  WndProc  returns  0  from  the  WM-QUERYOPEN  message.  This  keeps 
DDEPOP  displayed  as  an  icon  (similar  to  the  FREEMEM  program  in  Chapter  5). 

The  WM-DDE.INITIATE  Message 

A  DDE  conversation  is  initiated  by  a  client  by  broadcasting  a  WM_DDE_INITIATE  mes¬ 
sage  to  all  top-level  windows.  (As  you’ll  see  when  I  discuss  the  DDE  client  program  later  in 
this  chapter,  this  is  accomplished  by  calling  SendMessage  with  a  OxFFFF  window  handle  as 
the  first  parameter.) 


847 


SECTION  V:  DATA  EXCHANGE  AND  LINKS 


The  WM_DDE_INITIATE  message  is  handled  by  a  DDE  server  in  its  main  window 
procedure.  As  in  every  DDE  message,  the  wParam  parameter  is  the  handle  to  the  window 
sending  the  message.  This  is  the  window  handle  of  the  client.  WndProc  stores  this  in  the 
variable  hwndClient. 

For  the  WM_DDE_INITIATE  message,  the  low  word  of  IParam  is  the  atom  identify¬ 
ing  the  desired  application.  This  could  be  NULL  if  the  client  wants  a  response  from  any 
server.  The  high  word  of  IParam  is  the  atom  identifying  the  desired  topic.  Again,  this  could 
be  NULL  if  the  client  wants  a  response  from  a  server  that  can  supply  any  topic. 

WndProc  processes  the  WM_DDE_INITIATE  message  by  calling  Global AddAtom  to 
add  atoms  for  its  application  name  (“DdePopl”)  and  topic  name  (“US -Population”).  It  then 
checks  if  the  atoms  supplied  in  the  low  word  and  high  word  of  IParam  are  NULL  or  match 
these  atoms. 

If  the  atoms  match,  then  WndProc  creates  a  hidden  child  window  based  on  the 
“DdePopl. Server”  window  class.  This  window  (whose  window  procedure  is  ServerProc) 
will  handle  all  subsequent  DDE  messages  in  the  DDE  conversation.  The  first  of  the  two 
words  reserved  for  the  window  is  set  to  the  handle  of  the  client  using  SetWindowWord. 
WndProc  then  acknowledges  the  WM_DDE_INITIATE  message  by  sending  a  WM- 
_DDE_ACK  message  back  to  the  client.  The  wParam  parameter  is  the  handle  of  the  just- 
created  server  window,  and  IParam  contains  the  atoms  identifying  the  server  application 
name  and  the  topic  name.  (If  the  client  requested  all  topics  and  the  server  supports  mul¬ 
tiple  topics,  then  the  server  would  send  multiple  WM_DDE_ACK  messages  back  to  the 
client,  one  for  each  topic  it  supports.) 

A  program  that  receives  a  WM_DDE_ACK  message  is  responsible  for  deleting  all 
atoms  that  accompany  the  message.  WndProc  calls  GlobalDeleteAtom  for  the  two  atoms  it 
created  only  if  it  does  not  send  a  WM_DDE_ACK  message  to  the  client. 

The  WM_DDE_INITIATE  message  and  the  WM_DDE_ACK  message  (in  response  to 
WM_DDE_INITIATE)  are  the  only  two  DDE  messages  that  are  sent  using  SendMessage 
rather  than  posted  using  PostMessage.  As  we’ll  see  later  in  this  chapter,  this  means  that  a 
client  sending  a  WM_DDE_INITIATE  message  receives  the  WM_DDE_ACK  response 
before  the  original  SendMessage  call  has  returned. 

The  ServerProc  Window  Procedure 

With  the  sending  of  the  WM_DDE_ACK  message  in  response  to  the  WM_DDE_INITIATE 
message,  the  DDE  conversation  has  begun.  As  I  mentioned,  when  WndProc  sends  the 
WM_DDE_ACK  message  back  to  the  client,  it  sets  the  wParam  parameter  to  the  handle 
of  the  child  window  it  creates  for  the  conversation.  This  means  that  all  subsequent  DDE 
messages  occur  between  the  client  and  this  child  window,  whose  window  procedure 
is  ServerProc. 


848 


Chapter  17:  Dynamic  Data  Exchange  (DDE) 


ServerProc  processes  its  WM -CREATE  message  by  allocating  memory  required  to 
hold  NUM -STATES  structures  of  type  POPADVISE.  (I’ll  discuss  how  these  are  used 
shortly.)  The  handle  to  this  global  memory  block  is  stored  as  the  second  reserved  word 
using  SetWindowWord.  This  memory  block  is  freed  when  ServerProc  receives  a 
WM -DESTROY  message. 

The  WM_DDE_REQUEST  Message 

A  client  posts  a  WM_DDE -REQUEST  message  to  a  server  when  it  wants  data  that  is  associ¬ 
ated  with  a  particular  item.  This  is  the  type  of  transaction  known  as  the  cold  link.  The 
server  responds  by  posting  a  WM_DDE_DATA  message  to  the  client  with  the  data  or  a 
WM_DDE_ACK  message  if  it  cannot  satisfy  the  request.  Let’s  look  at  how  ServerProc 
handles  the  WM_DDE -REQUEST  message. 

As  is  usual  with  DDE  messages,  the  wParam  parameter  accompanying  WM_DDE- 
-REQUEST  is  the  handle  to  the  window  posting  the  message,  in  this  case  the  client.  The 
low  word  of  the  iParam  parameter  is  a  requested  data  format.  The  high  word  of  IParam  is 
an  atom  identifying  the  requested  data  item. 

The  formats  of  DDE  data  are  the  same  as  clipboard  formats,  so  this  low  word  of 
IParam  will  most  commonly  be  one  of  the  identifiers  beginning  with  the  CF  prefix.  A  cli¬ 
ent  may  send  multiple  WM_DDE_REQUEST  messages  to  a  server  for  the  same  item  but 
with  different  formats.  The  server  should  respond  with  a  WM_DDE_DATA  message  for 
only  the  formats  it  supports.  Far  and  away  the  most  common  format  for  DDE  data  is 
CF-TEXT,  and  this  is  the  only  format  that  DDEPOP1  supports. 

So,  when  processing  the  WM -DDE -REQUEST  message,  ServerProc  first  checks  if 
the  requested  format  is  CF-TEXT.  ServerProc  then  calls  the  GlobalGetAtomName  function 
to  get  the  character  string  associated  with  the  atom  passed  in  the  high  word  of  IParam.  If 
the  client  knows  what  it’s  doing,  this  will  be  a  two -character  string  identifying  the  state.  A 
for  loop  goes  through  the  states  and  attempts  to  match  this  with  the  szState  field  of  the  pop 
structure.  If  there’s  a  match,  ServerProc  deletes  the  atom  by  calling  GlobalDeleteAtom  and 
then  calls  PostDataMessage  (a  function  towards  the  end  of  DDEPOP1  that  posts  the 
WM_DDE_DATA  message,  which  I’ll  describe  shortly).  ServerProc  then  returns. 

If  the  requested  format  is  not  CF_TEXT,  or  if  there  was  no  match  between  the  item 
atom  and  one  of  the  state  names,  then  ServerProc  posts  a  negative  WM_DDE_ACK  mes¬ 
sage  indicating  that  the  data  was  not  available.  It  does  this  by  setting  the  fAck  field  of  a 
DDEACK  structure  (defined  in  DDE.H)  to  FALSE.  The  DDEACK  structure  is  converted  to  a 
word,  which  forms  the  low  word  of  IParam.  The  high  word  of  IParam  is  the  atom  for  the  re¬ 
quested  item.  PostMessage  posts  the  WM_DDE_ACK  message  to  the  client. 

Notice  how  the  atom  is  handled  here.  The  documentation  for  WM_DDE_REQUEST 
states:  “When  responding  with  either  a  WM_DDE_DATA  or  WM_DDE_ACK  message, 
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reuse  the  altem  atom  or  delete  it  and  create  a  new  one.”  What  this  means  is  that  the  state  of 
the  global  atom  table  should  not  be  altered  by  the  server — that  is,  the  reference  count  for 
the  item  atom  should  not  be  incremented  or  decremented. 

There  are  three  cases  here: 

■  If  the  requested  format  is  CF_TEXT  and  the  atom  matches  one  of  the  state 
names,  then  ServerProc  calls  GlobalDeleteAtom  before  calling  the 
function  in  DDEPOP1.C  named  PostDataMessage.  This  PostDataMessage 
function  (as  we’ll  see  shortly)  re-creates  the  atom  when  posting  a 
WM_DDE_DATA  message  to  the  client. 

■  If  the  requested  format  is  not  CF_TEXT  or  if  the  atom  does  not  match  one 
of  the  state  names,  then  ServerProc  calls  PostMessage  to  deliver  a  negative 
WM_DDE_ACK  message  to  the  client.  The  atom  is  simply  reused  in  this 
message. 

■  However,  if  this  PostMessage  call  fails  (perhaps  indicating  that  the  client 
has  been  unexpectedly  terminated),  then  ServerProc  deletes  the  atom 
because  the  client  cannot. 

We  are  not  yet  finished  with  the  WM_DDE_REQUEST  message  because  we  have 
not  yet  examined  how  DDEPOPl’s  PostDataMessage  responds  with  the  WM_DDE_DATA 
message.  That’s  next. 

DDEPOPl’s  PostDataMessage  Function 

The  PostDataMessage  function  towards  the  end  of  DDEPOP1.C  is  responsible  for  posting 
a  WM_DDE_DATA  message  to  a  client.  This  function  is  set  up  to  also  handle  WM- 
_DDE_ADVISE  messages  (which  I’ll  discuss  shortly),  so  it’s  a  little  more  complex  than 
if  it  only  had  to  handle  WM_DDE_REQUEST  messages. 

PostDataMessage  has  six  parameters: 

■  hwndServer — the  window  handle  of  the  server 

■  hwndClient — the  window  handle  of  the  client 

■  i — which  is  the  index  of  the  pop  array  identifying  the  state  for  which 
population  data  is  requested 

■  fDeferUpd — which  ServerProc  sets  to  FALSE  when  responding  to 
WM _DDE -REQUEST  messages 

■  fAckReq — which  ServerProc  also  sets  to  FALSE  in  this  case 

■  f Response — which  ServerProc  sets  to  TRUE  to  indicate  a  response  from  a 
WM  _DDE  .REQUEST  message 
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(I’ll  discuss  the  fDeferUpd  and  fAckReq  parameters  shortly  when  we  get  to  the 
WM_DDE_ADVISE  message.  For  now,  just  ignore  all  parts  of  PostDataMessage  when 
either  of  these  two  parameters  is  set  to  TRUE.) 

PostDataMessage  begins  by  calling  GlobalAddltem  to  create  an  atom  for  the  two- 
character  state  name.  (You’ll  recall  that  ServerProc  deleted  the  atom  before  calling 
PostDataMessage .)  It  then  calls  wsprintf  to  convert  the  population  of  the  state  (updated 
by  WndProc  within  the  past  5  seconds)  to  a  character  string  terminated  with  a  carriage 
return  and  line  feed. 

PostDataMessage  then  uses  GlobalAlloc  with  the  GMEM_DDESHARE  option  to  allo¬ 
cate  a  block  of  memory  large  enough  for  a  DDEDATA  structure  (defined  in  DDE.H)  with 
the  actual  data  (the  character  string  szPopulation )  appended  to  the  end.  In  the  case  of 
PostDataMessage  being  used  in  response  to  a  WM_DDE -REQUEST  message,  the  fields  of 
the  DDEDATA  structure  are  set  as  follows: 

■  The  /Response  field  of  the  DDEDATA  structure  is  set  to  TRUE,  indicating 
that  the  data  is  in  response  to  a  WM_DDE_DATA  message. 

■  The  /Release  field  is  also  set  to  TRUE,  indicating  that  the  client  should  free 
the  global  memory  block  just  allocated. 

■  The  fAckReq  field  is  set  to  FALSE,  indicating  that  a  WM_DDE_ACK 
message  from  the  client  is  not  required. 

■  The  cfFormat  field  is  set  to  CF_TEXT,  indicating  that  the  data  is  in  a  text 
format. 

■  The  szPopulation  array  is  copied  into  the  area  of  the  memory  block 
beginning  at  the  Value  field  of  the  structure. 

PostDataMessage  then  uses  PostMessage  to  post  a  WM_DDE_DATA  message  to  the 
client.  As  usual,  wParam  is  the  handle  of  the  window  sending  the  message  (the  server). 
The  low  word  of  iParam  is  the  handle  of  the  memory  block  containing  the  DDEDATA 
structure,  and  the  high  word  of  IParam  is  the  atom  identifying  the  data  item  (the  two- 
character  state  name). 

If  PostMessage  is  successful,  then  we’re  done.  The  client  is  responsible  for  freeing  the 
memory  block  and  deleting  the  atom.  If  PostMessage  fails  (perhaps  because  the  client  is  no 
longer  with  us),  PostDataMessage  trees  the  memory  block  it  allocated  and  deletes  the  atom. 

The  WM_DDE_ADVISE  Message 

You  are,  I  trust,  beginning  to  recognize  some  of  the  complexities  involved  in  DDE.  It  gets  a 
little  more  complex  with  WM_DDE_ADVISE  and  the  hot  link. 
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The  WM _DDE -REQUEST  message  I’ve  just  discussed  allows  the  client  to  obtain  data 
from  the  server.  But  if  this  data  changes  (as  the  instantaneous  population  will),  then  the 
client  has  no  way  to  know  that.  Allowing  the  client  to  know  when  data  has  been  updated  is 
the  purpose  of  the  WM_DDE_ADVISE  message.  On  receipt  of  this  message,  a  server  is  re¬ 
sponsible  for  notifying  the  client  when  the  data  has  changed.  (This  notification  is  accom¬ 
plished  by  the  server  posting  WM -DDE -DATA  messages  to  the  client.)  This  can  be  tricky 
because  the  server  must  “remember”  which  items  the  client  has  asked  to  be  advised  on. 
Moreover,  the  client  will  ask  that  this  data  be  posted  in  particular  ways. 

In  a  WM _DDE -ADVISE  message,  the  low  word  of  iParam  is  a  handle  to  a  global 
memory  block  containing  a  DDEADVISE  structure  as  defined  in  DDE.H.  The  high  word  of 
IParam  is  the  atom  identifying  the  data  item. 

When  processing  WM_DDE_ADVISE,  ServerProc  first  checks  that  the  cfFormat 
field  of  the  DDEADVISE  structure  is  CF-TEXT.  It  then  obtains  the  text  string  referenced  by 
the  atom  and  checks  it  against  the  szState  field  of  the  pop  structure. 

If  there’s  a  match,  then  ServerProc  gets  a  pointer  to  the  array  of  POPADVISE  struc¬ 
tures  that  it  allocated  during  the  WM -CREATE  message.  This  array  has  a  POPADVISE 
structure  for  each  state,  and  there  is  a  different  array  for  each  window  carrying  on  a  DDE 
conversation.  This  array  is  used  to  store  all  information  ServerProc  will  need  to  update 
items  to  the  client. 

The  fields  of  the  POPADVISE  structure  for  the  selected  state  are  set  as  follows: 

■  The  /Advise  field  is  set  to  TRUE.  This  is  simply  a  flag  that  indicates  that 
the  client  wants  updated  information  on  this  state. 

■  The  /DeferUpd  (“deferred  update”)  field  is  set  to  the  value  of  the  same 
field  in  the  DDEADVISE  structure.  A  FALSE  value  indicates  that  the  client 
wants  to  establish  a  warm  link  rather  than  a  hot  link.  The  client  will  be 
advised  of  a  change  in  data  without  getting  the  data  immediately.  (In  this 
case,  the  server  posts  a  WM_DDE_DATA  message  with  a  NULL  value 
rather  than  a  handle  to  the  global  memory  block  containing  a  DDEDATA 
structure.  The  client  will  later  post  a  normal  WM_DDE -REQUEST 
message  to  obtain  the  actual  data.)  A  TRUE  value  indicates  that  the  client 
wants  the  data  in  the  WM_DDE_DATA  message. 

■  The /AckReq  (“acknowledgment  requested”)  field  is  set  to  the  value  of  the 
same  field  in  the  DDEADVISE  structure.  This  is  a  very  tricky  value.  A  TRUE 
value  instructs  the  server  to  post  the  WM -DDE -DATA  with  the  /AckReq 
field  of  the  DDEDATA  structure  set  to  TRUE  so  that  the  client  is  required  to 
acknowledge  the  WM_DDE_DATA  message  with  a  WM_DDE_ACK 
message.  A  TRUE  value  does  not  mean  that  the  client  is  requesting  a 
WM_DDE_ACK  message  from  the  server;  it’s  requiring  that  the  server 
require  a  WM_DDE_ACK  message  from  the  client  when  later  posting  the 
WM_DDE_DATA  message. 
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■  The  iPopPrev  field  is  set  to  the  current  population  of  the  state.  ServerProc 
uses  this  field  to  determine  if  the  client  needs  notification  that  the 
population  has  changed. 

ServerProc  is  now  finished  with  the  DDEADVISE  structure  and  frees  the  memory 
block  as  the  documentation  for  WM_DDE -ADVISE  instructs.  ServerProc  must  now 
acknowledge  the  WM_DDE_ADVISE  message  by  posting  a  positive  WM_DDE_SBACK 
message.  The  fAck  field  of  the  DDEACK  structure  is  set  to  TRUE.  If  PostMessage  fails,  then 
ServerProc  deletes  the  atom. 

If  the  data  format  was  not  CF_TEXT,  or  if  there  was  no  match  for  the  state,  then 
ServerProc  posts  a  negative  WM_DDE_BACK  message.  In  this  case,  if  the  PostMessage 
call  fails,  ServerProc  both  deletes  the  atom  and  frees  the  DDEADVISE  memory  block. 

In  theory,  handling  of  the  WM_DDE_ADVISE  message  is  now  complete.  How¬ 
ever,  the  client  has  asked  that  it  be  notified  whenever  a  data  item  changes.  Given  that  the 
client  doesn’t  know  any  value  of  the  data  item,  it  is  necessary  for  ServerProc  to  post  a 
WM_DDE_DATA  message  to  the  client. 

It  does  this  using  the  PostDataMessage  function,  but  with  the  third  parameter 
set  to  the  fDeferUpd  field  of  the  POPADVISE  structure,  the  fourth  parameter  set  to  the 
fAckReq  field  of  the  POPADVISE  structure,  and  the  last  parameter  set  to  FALSE  (indicating 
a  WM_DDE_DATA  message  posted  in  response  to  WM_DDE_ADVISE  rather  than 
WM  -DDE  -REQUEST). 

It’s  time  for  another  look  at  PostDataMessage.  Toward  the  beginning  of  the  function, 
note  that  if  the  fDeferUpd  parameter  is  TRUE,  then  the  function  simply  sets  hDdeData  to 
NULL  rather  than  allocating  memory  for  it. 

If  the  fAckReq  parameter  is  TRUE,  then  PostDataMessage  waits  for  a  WM_DDE_ACK 
message  from  the  client  after  posting  the  WM_DDE_DATA  message.  It  does  this  by  calling 
PeekMessage.  PostDataMessage  deletes  the  atom  in  the  WM_DDE_ACK  message.  If  the 
WM_DDE_ACK  message  does  not  arrive  within  three  seconds — or  if  the  message  is  a 
negative  acknowledgment — then  PostDataMessage  frees  the  global  data  block  containing 
the  DDEDATA  structure. 

If  you  think  that  you  can  skip  over  part  of  this  work  by  assuming  that  a  client  will 
never  post  a  WM_DDE -ADVISE  message  with  the  deferred  update  or  acknowledgment 
requested  fields  set  to  TRUE,  guess  again.  Microsoft  Excel  does  precisely  that,  establishing 
a  warm  link  with  acknowledgments  to  the  WM_DDE_DATA  messages. 

Updating  the  Items 

After  processing  a  WM_DDE_ADVISE  message,  a  server  is  required  to  notify  the  client 
when  an  item  has  changed.  How  this  works  depends  on  the  server.  In  the  case  of  DDEPOP1, 
a  timer  is  used  to  recalculate  the  populations  every  5  seconds.  This  occurs  while  process¬ 
ing  the  WM -TIMER  message  in  WndProc. 
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WndProc  then  calls  EnumChildWindows  with  the  TimerEnumProc  function  (lo¬ 
cated  after  ServerProc  in  DDEPOP1.C).  TimerEnumProc  sends  WM_TIMER  messages  to  all 
the  child  windows,  all  of  which  will  be  using  the  ServerProc  window  procedure. 

ServerProc  processes  the  WM-TIMER  message  by  looping  through  all  the  states  and 
checking  if  the  POPADVISE  structure  field  /Advise  is  set  to  TRUE  and  the  population  has 
changed.  If  so,  it  calls  PostDataMessage  to  post  a  WM_DDE_DATA  message  to  the  client. 

The  WM_DDE_UNADVISE  Message 

The  WM_DDE_UNADVISE  message  instructs  a  server  to  stop  posting  WM_DDE_DATA 
messages  when  a  data  item  has  changed.  The  low  word  of  iParam  is  either  the  data  format 
or  0,  indicating  all  data  formats.  The  high  word  of  IParam  is  either  the  item  ATOM  or  NULL 
to  indicate  all  items. 

DDEPOP1  handles  the  WM_DDE_UNADVISE  message  by  setting  the  appropriate 
/Advise  fields  of  the  POPADVISE  structure  to  FALSE,  and  then  acknowledging  with  a  posi¬ 
tive  or  negative  WM_DDE_ACK  message. 

The  WM_DDE_TERMINATE  Message 

When  a  client  wishes  to  terminate  the  conversation,  it  posts  a  WM -DDE -TERMINATE 
message  to  the  server.  The  server  simply  responds  with  its  own  WM_DDE -TERMINATE 
message  back  to  the  client.  ServerProc  also  destroys  the  child  window  on  receipt  of 
WM _DDE -TERMINATE  because  it  is  no  longer  needed,  and  the  conversation  that  the 
window  has  maintained  is  terminated. 

ServerProc  also  processes  WM_DDE_POKE  and  WM_DDE_EXECUTE  messages, 
but  in  both  cases  simply  responds  with  a  negative  acknowledgment. 

If  DDEPOP1  is  closed  from  its  system  menu,  then  it  must  terminate  all  DDE 
conversations  with  its  clients.  So,  when  WndProc  receives  a  WM-CLOSE  message,  it  calls 
EnumChildWindows  with  the  CloseEnumProc  function.  CloseEnumProc  sends  WM- 
_CLOSE  messages  to  all  the  child  windows. 

ServerProc  responds  to  WM-CLOSE  by  posting  a  WM_DDE_TERMINATE  message 
to  the  client  and  then  waiting  for  another  WM_DDE -TERMINATE  message  back  from  the 
client. 


A  DDE  CLIENT  PROGRAM 

Now  that  we’ve  examined  a  DDE  server  program  that  you  can  use  with  Microsoft  Excel, 
let’s  examine  a  DDE  client  program  that  uses  DDEPOP1  as  a  server.  This  program  is  called 
SHOWPOP1  and  is  shown  in  Figure  17-2. 
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SHOWPOP1.MAK 

# . - . . 

#  SHOWPOPl.MAK  make  file 

#  . . 

showpopl.exe  :  showpopl.obj  showpopl.def 

$(WINLINK)  showpopl.  showpopl,  NUL,  $(WINLIB),  showpopl 
re  -t  showpopl.exe 

showpopl.obj  :  showpopl. c  showpop.h 
$ ( WI NCC )  showpopl. c 


SHOWPOP1.C 

/* . 

SH0WP0P1 . C  --  DDE  Client  using  DDEP0P1 
(c)  Charles  Petzold,  1992 
.  .  .  . */ 

♦include  <windows.h> 

#include  <dde.h> 

♦include  <stdlib.h> 

#include  <string.h> 

♦include  "showpop.h" 

♦define  WM_USER_I N ITI ATE  (WMJJSER  +  1) 

♦define  DDE_TIMEOUT  3000 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 
char  szAppName  []  =  "ShowPopl"  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 

LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( ihPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  s  CS.VREDRAW  ; 

wndclass. IpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

Figure  17-2.  The  SHOWPOP1  program.  (continued) 
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wndclass.cbWndExtra 

wndclass.hlnstance 

wndclass.hlcon 

wndclass.hCursor 

wndclass.hbrBackground 

wndclass.lpszMenuName 

wndclass.lpszClassName 


0  ; 

hlnstance  ; 

Loadlcon  (hlnstance,  szAppName) 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITE_BRUSH)  ; 
NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "DDE  Client  -  US  Population", 
WS.OVERLAPPEDWINDOW, 

CW_USEDEFAULT,  CW_USEDEFAULT, 
CW_USEDEFAULT,  CWJJSEDEFAULT. 

NULL,  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  nCmdShow)  ; 
UpdateWindow  (hwnd)  ; 


SendMessage  (hwnd,  WM_USER_I N ITI ATE ,  0,  0L)  ; 


while  (GetMessage  (&msg,  NULL,  0,  0)) 
{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 


static  BOOL 

f Doi nglni ti ate  =  TRUE  ; 

static  char 

szServerApp  []  =  "DdePopl", 

szTopic  []  =  "US.Population"  ; 

static  HWND 

hwndServer  =  NULL  ; 

static  short 

cxChar,  cyChar  ; 

ATOM 

aApp,  aTop,  altem  ; 

char 

szBuffer  [24],  szPopulation  [16],  szltem  [16] 

DDEACK 

DdeAck  ; 

DDEDATA  FAR 

*lpDdeData  ; 

DDEADVISE  FAR 

*lpDdeAdvise  ; 

DWORD 

dwTime  ; 

GLOBALHANDLE 

hDdeAdvise,  hDdeData  ; 

HDC 

hdc  ; 

MSG 

msg  ; 

PAINTSTRUCT 

ps  ; 

(continued) 
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short  i,  x,  y  ; 

TEXTMETRIC  tm  ; 

WORD  wStatus  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 

cxChar  =  tm.tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm. tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 
return  0  ; 

case  WM_USER_I N ITI ATE  : 

//  Broadcast  WM_DDE_I N ITI ATE  message 

aApp  =  GlobalAddAtom  (szServerApp)  ; 
aTop  =  GlobalAddAtom  (szTopic)  ; 

SendMessage  (0xFFFF,  WM_DDE_INITIATE,  hwnd. 

MAKELONG  (aApp,  aTop))  ; 

//  If  no  response,  try  loading  DDEP0P1  first 

if  (hwndServer  ==  NULL) 

{ 

WinExec  (szServerApp,  SW_SHOWMINNOACTIVE)  ; 

SendMessage  (0xFFFF,  WM_DDE_I N ITI ATE ,  hwnd. 

MAKELONG  (aApp,  aTop))  ; 

} 

//  Delete  the  atoms 

Global  Del eteAtom  (aApp)  ; 

Global  Del eteAtom  (aTop)  ; 
f Doi nglnitiate  =  FALSE  ; 

//  If  still  no  response,  display  message  box 

if  (hwndServer  ==  NULL) 

{ 

MessageBox  (hwnd,  "Cannot  connect  with  DDEP0P1.EXE!", 
szAppName,  MB.ICONEXCLAMATION  !  MB_0K)  ; 


return  0  ; 
} 


(continued) 
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//  Post  WM_DDE_ADVISE  messages 

for  (1  =  0  ;  1  <  NUM_STATES  ;  1++) 

{ 

hDdeAdvise  =  GlobalAlloc  (GHND  !  GMEM_DDESHARE, 

sizeof  (DDEADVISE) )  ; 

1 pDdeAdvise  =  (DDEADVISE  FAR  *)  G1 obal Lock  (hDdeAdvise)  ; 

lpDdeAdvise->fAckReq  =  TRUE  ; 
lpDdeAdvise->fDeferUpd  =  FALSE  ; 
lpDdeAdvise->cf Format  =  CF_TEXT  ; 

G1 obal Unlock  (hDdeAdvise)  ; 

altem  =  GlobalAddAtom  (pop[i ] .szAbb)  ; 

if  ( IPostMessage  (hwndServer,  WM_DDE_ADVISE,  hwnd, 
MAKELONG  (hDdeAdvise,  altem))) 

{ 

GlobalFree  (hDdeAdvise)  ; 

Global  Del eteAtom  (altem)  ; 
break  ; 

} 

DdeAck.fAck  =  FALSE  ; 

dwTime  =  GetCurrentTime  ()  ; 

while  (GetCurrentTime  0  -  dwTime  <  DDE_TIMEOUT) 

{ 

if  (PeekMessage  (&msg,  hwnd,  WM_DDE_ACK, 

WM_DDE_ACK,  PM_REM0VE) ) 

{ 

Global  Del eteAtom  ( HIWORD  (msg.lParam))  ; 

wStatus  =  LOWORD  (msg.lParam)  ; 

DdeAck  =  *  (DDEACK  *)  &  wStatus  ; 

if  (DdeAck.fAck  ==  FALSE) 

GlobalFree  (hDdeAdvise)  ; 

break  ; 

} 

} 

if  (DdeAck.fAck  ==  FALSE) 
break  ; 


(continued) 
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while  (PeekMessage  (&msg,  hwnd.  WM_DDE_FIRST, 
WM_DDE_LAST,  PM_REMOVE) ) 

{ 

DispatchMessage  (&msg)  ; 

} 

} 

if  (i  <  NUM_STATES) 

{ 

MessageBox  (hwnd,  "Failure  on  WM_DDE_ADVISE!", 

szAppName,  MB_ICONEXCLAMATION  !  MB_0K)  ; 

} 

return  0  ; 
case  WM_DDE_ACK  : 

//  In  response  to  WM_DDE_INITIATE,  save  server  window 

if  (fDoi nglni ti ate) 

{ 

hwndServer  =  wParam  ; 

Global  Del eteAtom  ( LOWORD  ( 1  Pa  ram) )  ; 

Global  Del eteAtom  (HIWORD  (lParam))  ; 

} 

return  0  ; 
case  WM_DDE_DATA  : 

//  wParam  --  sending  window  handle 

//  LOWORD  (lParam)  --  DDEDATA  memory  handle 
//  HIWORD  (lParam)  --  item  atom 

hDdeData  =  LOWORD  (lParam)  ; 

IpDdeData  =  (DDEDATA  FAR  *)  Global  Lock  (hDdeData)  ; 
altem  =  HIWORD  (lParam)  ; 

//  Initialize  DdeAck  structure 

DdeAck.bAppReturnCode  =  0  ; 

DdeAck. reserved  =  0  ; 

DdeAck. fBusy  =  FALSE  ; 

DdeAck. fAck  =  FALSE  ; 

//  Check  for  matching  format  and  data  item 

if  (lpDdeData->cfFormat  ==  CF_TEXT) 

{ 

Global GetAtomName  (altem,  szltem,  sizeof  (szltem))  ; 
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for  (i  =  0  ;  i  <  NUM.STATES  ;  i++) 

if  (strcmp  (szltem,  pop[i ] . szAbb)  ==  0) 
break  ; 

if  (i  <  NUM_STATES) 

{ 

lstrcpy  ( szPopul ati on ,  (char  FAR  *)  lpDdeData->Value)  ; 
pop[i].lPop  =  atol  (szPopul ati on )  ; 

I rvval i dateRect  (hwnd,  NULL,  FALSE)  ; 

DdeAck.fAck  =  TRUE  ; 

} 

} 

//  Acknowledge  if  necessary 

if  (lpDdeData->fAckReq  ==  TRUE) 

{ 

wStatus  =  *  (WORD  *)  &  DdeAck  ; 

if  ( ! PostMessage  (wParam,  WM_DDE_ACK,  hwnd, 

MAKELONG  (wStatus,  altem) ) ) 

{ 

Global  Del eteAtom  (altem)  ; 

G1 obal Unlock  (hDdeData)  ; 

G1 obal Free  (hDdeData)  ; 
return  0  ; 

} 

) 

else 

{ 

Global  Del eteAtom  (altem)  ; 

} 

//  Clean  up 

if  (lpDdeData->fRelease  ==  TRUE  !!  DdeAck.fAck  ==  FALSE) 

{ 

GlobalUnlock  (hDdeData)  ; 

G1 obal Free  (hDdeData)  ; 

} 

else 

{ 

GlobalUnlock  (hDdeData)  ; 

} 

return  0  ; 
case  WM__PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 


(continued) 
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for  (i  =  0  ;  1  <  NUM_STATES  ;  i++) 

{ 

if  (i  <  (NUM_STATES  +  1)  /  2) 

{ 

x  =  cxChar  ; 
y  =  i  *  cyChar  ; 

} 

else 

{ 

x  =  44  *  cxChar  ; 

y  =  (i  -  (NUM_STATES  +  1)  /  2)  *  cyChar  ; 

} 

TextOut  (hdc,  x,  y,  szBuffer, 

wsprintf  (szBuffer,  "%-20s", 

(LPSTR)  pop[i] .szState))  ; 

x  +=  36  *  cxChar  ; 

SetTextAl ign  (hdc,  TA_RIGHT  !  TA_T0P)  ; 

TextOut  (hdc,  x,  y,  szBuffer, 

wsprintf  (szBuffer,  "%101d",  pop[i ] . 1  Pop) )  ; 

SetTextAl ign  (hdc,  TA_LEFT  :  TA_T0P)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DDE_TERM I  NATE  : 

//  Respond  with  another  WM_DDE_TERMI NATE  message 

PostMessage  (hwndServer,  WM_DDE_TERM I  NATE ,  hwnd,  0L)  ; 
hwndServer  =  NULL  ; 
return  0  ; 

case  WM_C LOSE  : 

if  (hwndServer  ==  NULL) 
break  ; 

//  Post  WM_DDE_UNADVISE  message 

PostMessage  (hwndServer,  WM_DDE_UNADVISE,  hwnd, 

MAKELONG  (CFJTEXT,  NULL))  ; 

dwTime  =  GetCurrentTime  0  ; 


(continued) 
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while  (GetCurrentTime  ()  -  dwTime  <  DDE_TIMEOUT) 

{ 

if  (PeekMessage  (&msg,  hwnd,  WM_DDE_ACK, 
WM_DDE_ACK,  PM_REM0VE) ) 

break  ; 

} 

//  Post  WM_DDE_TERMI NATE  message 

PostMessage  (hwndS erver,  WM_DDE_TERMI NATE ,  hwnd,  0L)  ; 

dwTime  =  GetCurrentTime  0  ; 

while  (GetCurrentTime  0  -  dwTime  <  DDE_TIMEOUT) 

{ 

if  (PeekMessage  (&msg,  hwnd,  WM_DDE_TERMINATE, 
WM_DDE_TERMI NATE ,  PM_REM0VE) ) 

break  ; 

} 

break  ;  //  for  default  processing 

case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWi ndowProc  (hwnd,  message,  wParam,  IParam)  ; 


SHOWPOP.H 


/* . . . 

SHOWPOP.H  header  file 
. - . -*/ 


struct 

{ 

char  *szAbb  ; 
char  *szState  ; 
long  1  Pop  ; 

} 

pop  []  =  { 

MAL",  "Alabama", 

"AZ",  "Arizona", 

"CA",  "California", 

"CT",  "Connecticut", 

"DC",  "Dist.  of  Columbia", 


0, 

"AK", 

"Alaska", 

0, 

0, 

"AR", 

"Arkansas", 

0, 

0, 

"CO", 

"Colorado", 

0, 

0. 

"DE", 

"Delaware", 

0, 

0, 

"FL", 

"Florida", 

0. 

(continued) 
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"GA",  "Georgia",  0, 
"ID",  "Idaho",  0, 
"IN",  "Indiana",  0, 
"KS",  "Kansas".  0, 
"LA",  "Louisiana".  0, 
"MD".  "Maryland",  0, 
"MI",  "Michigan",  0, 
"MS",  "Mississippi".  0, 
"MT".  "Montana".  0, 
"NV",  "Nevada".  0, 
"NJ",  "New  Jersey",  0. 
"NY",  "New  York",  0, 
"ND",  "North  Dakota",  0, 
"OK".  "Oklahoma",  0, 
"PA",  "Pennsylvania".  0, 
"SC".  "South  Carolina",  0. 
"TN",  "Tennessee".  0, 
"UT".  "Utah",  0, 
"V A",  "Virginia",  0, 
"WV",  "West  Virginia",  0, 
"WY".  "Wyoming",  0, 
}  ; 


HI". 

"Hawaii", 

0, 

IL", 

"Illinois", 

0, 

I  A", 

"Iowa", 

0, 

KY", 

"Kentucky", 

0. 

ME", 

"Maine". 

0. 

MA". 

"Massachusetts", 

0, 

MN", 

"Minnesota", 

0, 

MO". 

"Missouri", 

0, 

NE". 

"Nebraska", 

0, 

NH", 

"New  Hampshire", 

0, 

NM", 

"New  Mexico". 

0, 

’NC". 

"North  Carolina", 

0, 

'OH", 

"Ohio". 

0. 

’OR", 

"Oregon", 

0. 

'RI", 

"Rhode  Island", 

0. 

’SD", 

"South  Dakota", 

0. 

TX", 

"Texas". 

0, 

VT". 

"Vermont", 

0, 

'WA", 

"Washington", 

0, 

WI", 

"Wisconsin", 

0, 

US", 

"United  States  Total" 

.  0 

#define  NUM_STATES  (sizeof  (pop)  /  sizeof  (pop  [0])) 


SHOWPOP1.DEF 


;  SH0WP0P1.DEF  module  definition  file 


NAME 


SH0WP0P1 


DESCRIPTION  ’DDE  Population  Client  (c)  Charles  Petzold,  1992’ 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


This  program  displays  the  names  of  the  states  in  its  window  with  the  updated  populations 
obtained  from  DDEPOP1  using  the  WM_DDE_ADVISE  facility.  You’ll  note  that  SHOWPOP1 
contains  a  structure  called  pop  just  like  DDEPOP1,  but  this  version  contains  the  two-letter 
state  abbreviations,  the  state  names,  and  a  field  called  iPop  (initialized  with  zeros)  that  will 
contain  the  updated  populations  obtained  from  DDEPOP1. 
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SHOWPOP1  carries  on  only  one  DDE  conversation,  so  it  needs  only  one  window  for 
this  conversation,  and  it  uses  WndProc  for  this  purpose. 

Initiating  the  DDE  Conversation 

I’ve  chosen  to  initiate  the  DDE  conversation  by  sending  WndProc  a  user-defined  message 
(which  I’ve  called  WM_USER_INITIATE)  after  the  UpdateWindow  call  in  WinMain. 
Normally  a  client  would  initiate  the  conversation  in  response  to  a  menu  command. 

In  response  to  this  user-defined  message,  WndProc  calls  GlobalAddAtom  to  create 
atoms  for  the  application  name  of  the  server  (“DdePopl”)  and  the  topic  name  (“US_Popu- 
lation”).  WndProc  broadcasts  the  WM_DDE -INITIATE  message  by  calling  SendMessage 
with  a  OxFFFF  window  handle. 

As  we’ve  seen,  a  server  that  scores  a  match  with  the  application  and  topic  atoms  is 
required  to  send  a  WM_DDE_ACK  message  back  to  the  client.  Because  this  message  is  sent 
using  SendMessage  rather  than  posted,  the  client  will  receive  the  WM_DDE_ACK  message 
before  the  original  SendMessage  call  with  the  WM_DDE_INITIATE  message  has  returned. 
WndProc  handles  the  WM_DDE_ACK  message  by  storing  the  window  handle  of  the  server 
in  the  variable  hwndServer  and  deleting  the  atoms  that  accompany  the  message. 

If  a  client  broadcasts  a  WM_DDE_INITIATE  message  with  NULL  application  or  topic 
names,  then  it  must  be  prepared  to  receive  multiple  WM_DDE_ACK  messages  from  each 
of  the  servers  that  can  satisfy  the  request.  In  this  case,  the  client  must  decide  which  server 
to  use.  The  others  must  be  posted  WM_DDE_TERMINATE  messages  to  terminate  the 
conversation. 

It  is  possible  that  hwndServer  will  still  be  NULL  after  the  WM_DDE_INITIATE 
SendMessage  call.  This  means  that  DDEPOP1  is  not  running  under  Windows.  In  this  case, 
WndProc  attempts  to  execute  DDEPOP1  by  calling  WinExec.  The  WinExec  call  searches 
the  current  directory  and  the  PATH  environment  variable  to  load  DDEPOPl.  WndProc  then 
again  broadcasts  the  WM_DDE -INITIATE  message.  If  hwndServer  is  still  NULL,  then 
WndProc  displays  a  message  box  notifying  the  user  of  the  problem. 

Next,  for  each  of  the  states  listed  in  the  pop  structure,  WndProc  allocates  a  DDE- 
ADVISE  structure  by  calling  GlobalAlloc  with  the  GMEM_DDESHARE  flag.  The  fAckReq 
(“acknowledgment  requested”)  flag  is  set  to  TRUE  (indicating  that  the  server  should  post 
WM_DDE_DATA  messages  with  the  fAckReq  field  in  the  DDEDATA  field  set  to  NULL).  The 
fDeferUpd  flag  is  set  to  FALSE  (indicating  a  hot  link  rather  than  a  warm  link),  and  the 
cfFormat  field  is  set  to  CF_TEXT.  GlobalAddAtom  adds  an  atom  for  the  two-letter  state 
abbreviation. 

This  structure  and  the  atom  are  passed  to  the  server  when  SHOWPOP1  posts  the 
WM_DDE -ADVISE  message.  If  the  PostMessage  call  fails  (which  might  happen  if 
DDEPOP1  is  suddenly  terminated),  then  SHOWPOP1  frees  the  memory  block,  deletes  the 
atom,  and  exits  the  loop. 
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Otherwise,  SHOWPOP1  waits  for  a  WM_DDE_ACK  message  by  calling  PeekMessage. 
As  the  DDE  documentation  indicates,  the  client  deletes  the  atom  accompanying  the  mes¬ 
sage,  and  also  frees  the  global  memory  block  if  the  client  responds  with  a  negative 
acknowledgment. 

It’s  quite  likely  that  this  WM_DDE_ACK  message  from  the  client  will  be  followed  by 
a  WM_DDE_DATA  message  for  the  item.  For  this  reason,  SHOWPOP1  calls  PeekMessage 
and  Dispatch  Message  to  extract  any  DDE  messages  from  the  message  queue  and  dispatch 
them  to  WndProc. 

The  WM_DDE_DATA  Message 

Following  the  WM_DDE_ADVISE  messages,  WndProc  will  receive  WM_DDE_DATA  mes¬ 
sages  from  the  server  containing  updated  population  data.  The  low  word  of  iParam  is  a 
memory  handle  to  a  global  block  containing  a  WM_DDE_DATA  structure,  and  the  high 
word  of  IParam  is  the  atom  identifying  the  data  item. 

SHOWPOP1  checks  if  the  cfFormat  field  of  the  DDEDATA  structure  is  CF-TEXT.  (Of 
course,  we  know  that  DDEPOP1  uses  CF_TEXT  exclusively,  but  this  is  just  for  the  sake  of 
completeness.)  It  then  obtains  the  text  string  associated  with  the  item  atom  by  calling 
GlobalGetAtomName.  This  text  string  is  the  two-letter  state  abbreviation. 

Using  a  for  loop,  SHOWPOP1  scans  through  the  states  looking  for  a  match.  If  it  finds 
one,  it  copies  the  population  data  from  the  DDEDATA  structure  into  the  szPopulation 
array,  converts  it  to  a  long  integer  using  the  C  function  atol  (“ASCII  to  long”),  stores  it  in 
the  pop  structure,  and  invalidates  the  window. 

All  that  remains  now  is  cleaning  up.  If  the  client  requested  an  acknowledgment  of 
the  WM_DDE_DATA  message,  WndProc  posts  one.  If  no  acknowledgment  was  requested 
(or  if  the  PostMessage  call  fails),  then  the  item  atom  is  deleted.  If  the  PostMessage  call  fails, 
or  if  there  was  no  match  on  the  state  (indicating  a  negative  acknowledgment),  or  if  the 
/Release  flag  in  the  DDEDATA  structure  is  set  to  TRUE,  then  SHOWPOP1  frees  the  memory 
block. 

I  originally  wrote  SHOWPOP1  so  that  it  posted  WM_DDE_ADVISE  messages  with 
the  fAckReq  field  of  the  DDEADVISE  structure  set  to  FALSE.  This  indicates  to  the  server 
that  the  WM_DDE_DATA  messages  should  be  posted  with  the  fAckReq  field  of  the 
DDEDATA  structure  set  to  FALSE,  which  in  turn  indicates  to  the  client  that  it  should  not 
post  WM_DDE_ACK  messages  to  the  server  acknowledging  the  WM_DDE_DATA  mes¬ 
sages.  This  worked  fine  for  normal  updates.  However,  if  I  changed  the  system  time  in  Win¬ 
dows  while  SHOWPOP1  was  running,  then  DDEPOP1  posted  52  WM_DDE_DATA  messages 
to  SHOWPOP1  without  waiting  for  acknowledgment.  This  caused  SHOWPOPl’s  message 
queue  to  overflow,  and  it  lost  many  of  the  updated  populations. 

The  lesson  is  clear:  If  a  client  wishes  to  be  advised  of  many  data  items  that  can 
change  all  at  once,  then  it  must  set  the  fAckReq  field  of  the  DDEADVISE  structure  to  TRUE. 
This  is  the  only  safe  approach. 


865 


SECTION  V:  DATA  EXCHANGE  AND  LINKS 


The  WM_DDE_TERMINATE  Message 

Handling  a  WM_DDE_TERMINATE  message  posted  by  the  server  is  simple:  SHOWPOP1 
simply  posts  another  WM_DDE -TERMINATE  message  back  to  the  client  and  sets  the 
hwndServer  variable  to  NULL  (indicating  the  conversation  is  over). 

If  SHOWPOP1  is  closed  (indicated  by  a  WM-CLOSE  message),  then  the  program  first 
posts  a  WM_DDE_UNADVISE  message  to  the  server  to  prevent  any  future  updates.  This 
uses  a  NULL  item  atom  to  indicate  all  data  items.  SHOWPOP1  then  posts  a  WM_DDE_TER- 
MINATE  message  to  the  server  and  waits  for  a  WM_DDE_TERMINATE  message  to  return 
back  from  the  server. 


THE  DDE  MANAGEMENT  LIBRARY 

Because  of  the  complexity  that  many  programmers  encountered  when  using  DDE, 
Microsoft  decided  to  give  it  a  new  look  and  feel.  The  DDE  Management  Library  (DDEML) 
hides  many  of  the  complexities  of  DDE  by  encapsulation  of  messages,  atom  management, 
and  memory  management  in  a  function  call  interface. 

DDEML  may  appear  daunting  at  first.  The  DDEML.H  header  file  defines  27  function 
calls  beginning  with  the  prefix  Dde.  A  program  using  DDEML  also  requires  a  call-back 
function  that  can  process  16  transaction  types.  These  are  constants  defined  in  DDEML.H 
beginning  with  the  prefix  XTYP 

The  good  news  is  that  DDEML  does  simplify  DDE  programming.  This  will  be  ob¬ 
vious  in  the  code  lengths  of  the  DDEPOP2.C  and  SHOWPOP2.C  source  code  files,  which 
are  functionally  equivalent  to  DDEPOP1  and  SHOWPOP1. 

Conceptual  Differences 

There  are  some  terminology  and  conceptual  differences  between  using  classic  DDE  and 
using  DDEML.  First,  although  DDE  transactions  are  still  based  on  application,  topic,  and 
item  names,  in  DDEML  the  application  name  is  called  the  “service”  name. 

Any  program  that  uses  DDEML  must  first  register  itself  with  the  DDE  Management 
Library  by  calling  Ddelnitialize.  This  function  obtains  an  application  instance  identifier 
that  is  passed  to  all  other  DDEML  functions.  When  the  program  terminates,  it  calls 
DdeUnini  tial  ize. 

The  most  significant  difference  between  classic  DDE  and  DDEML  is  that  a  program 
processes  DDE  transactions  in  a  call-back  function  rather  than  a  window  procedure.  This 
call-back  function  is  registered  with  the  system  in  the  Ddelnitialize  c all. 

When  passing  data  from  one  application  to  another,  a  program  does  not  directly  allo¬ 
cate  shared  global  memory.  Instead,  the  program  creates  a  data  handle  from  a  buffer  con¬ 
taining  the  data,  through  a  call  to  DdeCreateDataHandle.  The  program  receiving  the  data 
obtains  the  data  from  the  handle  using  DdeAccessData  or  DdeGetData .  The  data  handle  is 
freed  by  calling  DdeFreeDataHandle. 
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Rather  than  using  atoms,  a  DDEML  program  uses  string  handles,  which  are  stored  in 
variables  of  type  HSZ.  The  DdeCreateStringHandle  function  creates  a  string  handle  from  a 
character  string,  DdeQuery String  obtains  a  string  from  the  handle,  DdeCmpStringHandles 
compares  the  strings  represented  by  two  string  handles,  and  DdeFreeStringHandle  frees  a 
string  handle.  In  some  cases,  string  handles  are  freed  automatically.  A  program  can  keep  a 
string  handle  valid  by  calling  DdeKeepStringHandle. 

DDE  the  DDEML  Way 

Let’s  jump  right  into  the  sample  code  to  see  how  DDEML  works  in  a  real-life  application. 
Figure  17-3  shows  the  source  code  for  a  DDEML  server  called  DDEPOP2,  and  Figure  17-4 
shows  the  source  code  for  a  DDEML  client  named  SHOWPOP2.  The  DDEPOP2  program 
also  requires  the  DDEPOP.H  and  DDEPOP.ICO  files  from  Figure  17-1,  and  the  SHOWPOP2 
program  requires  the  SHOWPOP.H  file  from  Figure  17-2. 

DDEPOP2.MAK 

#-  — . 

#  DDEP0P2.MAK  make  file 

#- . . . 

ddepop2.exe  :  ddepop2.obj  ddepop2.def  ddepop2.res 

$ ( WI NLI NK)  ddepop2,  ddepop2,  NUL,  $(WINLIB),  ddepop2 
rc  -t  ddepop2.res 

ddepop2.obj  :  ddepop2.c  ddepop.h 
$ ( W I NCC )  ddepop2.c 

ddepop2.res  :  ddepop2.rc  ddepop.ico 
$ ( WI NRC )  ddepop2. rc 


DDEPOP2.C 


I  * _ 

DDEP0P2.C 


DDEML  Server  for  Population  Data 
(c)  Charles  Petzold,  1992 
- - - */ 


#include  <windows.h> 

^include  <ddeml.h> 

#include  <string.h> 
finclude  "ddepop.h" 

Figure  17-3.  The  DDEPOP2 program .  (continued) 
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#define  WM_USER_INITIATE  (WM.USER  +  1) 

^define  ID.TIMER  1 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

HDDEDATA  FAR  PASCAL  .export  DdeCal 1  back  (UINT,  UINT,  HCONV,  HSZ,  HSZ, 

HDDEDATA,  DWORD.  DWORD)  ; 


char  szAppName  [] 

char  szTopic  [] 

DWORD  idlnst  ; 
HANDLE  hlnst  ; 

HWND  hwnd  ; 


"DdePop2”  ; 
"US.Population" 


int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

FARPROC  pfnDdeCal 1  back  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  (hPrevInstance) 
return  FALSE  ; 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndcl ass. hbrBackg round 
wndclass. IpszMenuName 
wndclass. IpszClassName 


=  0  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  Loadlcon  (hlnstance,  szAppName)  ; 
=  LoadCursor  (NULL,  IDC.ARROW)  ; 

=  GetStockObject  (WHITE.BRUSH)  ; 

=  NULL  ; 

=  szAppName  ; 


RegisterClass  (Swndclass)  ; 


hwnd  =  CreateWindow  (szAppName,  "DDEML  Population  Server", 
WS_0V  ERLAPPEDWI NDOW , 

CW.USEDEFAULT,  CW.USEDEFAULT, 
CW.USEDEFAULT,  CW.USEDEFAULT, 

NULL.  NULL,  hlnstance,  NULL)  ; 


ShowWindow  (hwnd,  SW.SHOWMINNOACTIVE)  ; 

UpdateWindow  (hwnd)  ; 

//  Initialize  for  using  DDEML 

pfnDdeCal 1  back  =  MakeProcInstance  ((FARPROC)  DdeCal 1  back ,  hlnstance)  ; 

if  (Ddelnitial ize  (&i dlnst .  (PFNCALLBACK)  pfnDdeCal lback, 

CBF.FAI L.EXECUTES  !  CBF.FAI L.P0KES  ! 

CBF.SKI P.REG I  STRATI ONS  !  CB F.SKI P.UNREGI STRATIONS ,  0L)) 
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{ 

MessageBox  (hwnd,  "Could  not  initialize  server!", 

szAppName,  MB_I CON EXC LAMATI ON  !  MB_0K)  ; 

DestroyWindow  (hwnd)  ; 
return  FALSE  ; 

} 

//  Set  the  timer 

if  USetTimer  (hwnd,  I D_T I M E R ,  5000,  NULL)) 

{ 

MessageBox  (hwnd,  "Too  many  clocks  or  timers!",  szAppName, 
MB_ICONEXCLAMATI ON  !  MB_0K)  ; 

DestroyWindow  (hwnd)  ; 
return  FALSE  ; 

} 


//  Get  things  going 

SendMessage  (hwnd,  WM_USER_INITIATE,  0,  0L)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

//  Clean  up 

DdeUninitialize  (idlnst)  ; 

Kill  Timer  (hwnd,  ID.TIMER)  ; 

return  msg.wParam  ; 

} 

int  GetStateNumber  (UINT  iFmt,  HSZ  hszltem) 

{ 

char  szltem  [32]  ; 
int  i  ; 

if  (iFmt  !=  CF.TEXT) 
return  -1  ; 

DdeQueryString  (idlnst,  hszltem,  szltem,  sizeof  (szltem),  0)  ; 

for  (i  =  0  ;  i  <  NUM.STATES  ;  i++) 

if  (strcmp  (szltem,  pop[i].szState)  ==  0) 
break  ; 

if  (i  >=  NUM.STATES) 
return  -1  ; 
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return  i  ; 

} 

HDDEDATA  FAR  PASCAL  .export  DdeCal 1  back  (UINT  iType,  UINT  iFmt,  HCONV  hConv, 

HSZ  hszl,  HSZ  hsz2,  HDDEDATA  hData, 
DWORD  dwDatal,  DWORD  dwData2) 

{ 

char  szBuffer  [32]  ; 
int  i  ; 

switch  (iType) 

{ 

case  XTYP.CONNECT  :  //  hszl  =  topic 

//  hsz2  =  service 

DdeQueryString  (idlnst,  hsz2,  szBuffer,  sizeof  (szBuffer),  0)  ; 

if  (0  !=  strcmp  (szBuffer,  szAppNane)) 
return  FALSE  ; 

DdeQueryString  (idlnst,  hszl,  szBuffer,  sizeof  (szBuffer),  0)  ; 

if  (0  !=  strcmp  (szBuffer,  szTopic)) 
return  FALSE  ; 

return  TRUE  ; 

case  XTYP.ADVSTART  :  //  hszl  =  topic 

//  hsz2  =  item 

//  Check  for  matching  format  and  data  item 

if  (-1  ==  (i  =  GetStateNumber  (iFmt,  hsz2))) 
return  FALSE  ; 

pop[i ] . 1 PopLast  =  0  ; 

PostMessage  (hwnd,  WM.TIMER,  0,  0L)  ; 

return  TRUE  ; 

case  XTYP.REQUEST  : 

case  XTYP.ADVREQ  :  //  hszl  =  topic 

//  hsz2  =  item 

//  Check  for  matching  format  and  data  item 

if  (-1  ==  (i  =  GetStateNumber  (iFmt,  hsz2))) 
return  NULL  ; 

wsprintf  (szBuffer,  "JKldYrXn",  pop[i ] .  1  Pop)  ; 
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return  DdeCreateDataHandle  (idlnst,  szBuffer, 

strlen  (szBuffer)  +  1, 

0.  hsz2,  CF_TEXT,  0)  ; 

case  XTYP_ADVSTOP  :  //  hszl  =  topic 

//  hsz2  =  item 

//  Check  for  matching  format  and  data  item 

if  (-1  ==  (i  =  GetStateNumber  (iFmt,  hsz2))) 
return  FALSE  ; 

return  TRUE  ; 

} 

return  NULL  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HSZ  hszService,  hszTopic  ; 

HSZ  hszltem  ; 

int  i  ; 

switch  (message) 

{ 

case  WM_USER_I NITI ATE  : 

InitPops  0  ; 

hszService  =  DdeCreateStringHandle  (idlnst,  szAppName,  0)  ; 
hszTopic  =  DdeCreateStringHandle  (idlnst,  szTopic,  0)  ; 

DdeNameService  (idlnst,  hszService,  NULL,  DNS.REGISTER)  ; 
return  0  ; 

case  WM.TIMER  : 
case  WM.TIMECHANGE  : 

//  Calculate  new  current  populations 

CalcPops  ()  ; 

for  (i  =  0  ;  i  <  NUM.STATES  ;  i++) 

if  ( pop[i ] . 1  Pop  !=  pop[i ] . 1 PopLast ) 

{ 

hszltem  =  DdeCreateStringHandle  (idlnst, 

pop[i].szState,  0)  ; 

DdePostAdvise  (idlnst,  hszTopic,  hszltem)  ; 
DdeFreeStringHandle  (idlnst,  hszltem)  ; 
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pop[i ] .1 PopLast  =  pop[i ] . 1  Pop  ; 
} 


return  0  ; 

case  WM.QUERYOPEN  : 
return  0  ; 

case  WMJ3ESTR0Y  : 

DdeNameService  (id Inst „  hszService,  NULL,  DNS_UNREGI STER)  ; 
DdeFreeStringHandle  (idlnst,  hszService)  ; 
DdeFreeStringHandle  (idlnst,  hszTopic)  ; 

PostQuitMessage  (0)  ; 
return  0  ,* 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 


DDEPOP2.RC 

/* . 

DDEP0P2.RC  resource  script 
. - . . . */ 

DdePop2  ICON  ddepop.ico 


DDEPOP2.DEF 


DDEP0P2.DEF  module  definition  file 


NAME  DDEP0P2 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


' DDEML  Server  for  Population  Data  (c)  Charles  Petzold,  1992' 

WINDOWS 

’WINSTUB. EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 
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SHOWPOP2.MAK 

# 

#  SH0WP0P2.MAK  make  file 

#  . - . 

showpop2.exe  :  showpop2.obj  showpop2.def 

$(WINLINK)  showpop2,  showpop2,  NUL,  $(WINLIB),  showpop2 
rc  -t  showpop2.exe 

showpop2.obj  :  showpop2.c  showpop.h 
$ ( WI NCC )  showpop2.c 


SHOWPOP2.C 


/* . 

SH0WP0P2.C  --  DDEML  Client  using  DDEP0P2 
(c)  Charles  Petzold,  1992 
. */ 


♦include  <windows.h> 

♦include  <ddeml.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  "showpop.h" 

♦define  WM_USER_I NITI ATE  (WM_USER  +  1) 

♦define  DDE_T I MEOUT  3000 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT.  LONG)  ; 

HDDEDATA  FAR  PASCAL  .export  DdeCal 1  back  (UINT,  UINT,  HCONV,  HSZ,  HSZ, 

HDDEDATA,  DWORD,  DWORD)  ; 


char  szAppName  []  =  "ShowPop2"  ; 

DWORD  idlnst  ; 

HCONV  hConv  ; 

HWND  hwnd  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

MSG  msg  ; 

FARPROC  pfnDdeCal 1  back  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 


Figure  17-4.  The  SHOWPOP2 program. 
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wndclass. style 
wndclass.lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. lpszMenuName 
wndclass. 1 pszCl assName 


CS.HREDRAW  !  CSJ/REDRAW  ; 

WndProc  ; 

0  ; 

0  ; 

hlnstance  ; 

Loadlcon  (hlnstance,  szAppName)  ; 
LoadCursor  (NULL,  IDC_ARR0W)  ; 
GetStockObject  (WHITE_BRUSH)  ; 
NULL  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 
} 


hwnd  =  CreateWindow  (szAppName,  "DDEML  Client  -  US  Population", 
WS.OVERLAPPEDWINDOW, 

CW_USEDEFAULT,  CW.USEDEFAULT, 

CW_USEDEFAULT,  CW_USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

//  Initialize  for  using  DDEML 

pf nDdeCal 1  back  =  MakeProcInstance  ( ( FARPROC )  DdeCal 1  back ,  hlnstance)  ; 

if  (Ddelnitialize  (&idlnst,  ( PFNCALLBACK)  pf nDdeCal 1  back , 

APPCLASS_STANDARD  !  APPCMD_CLI ENTONLY ,  0L)) 

{ 

MessageBox  (hwnd,  "Could  not  initialize  client!", 

szAppName,  MB_I CON EXC LAMAT ION  !  MB_0K)  ; 

DestroyWindow  (hwnd)  ; 
return  FALSE  ; 

} 


//  Get  things  going 

SendMessage  (hwnd,  WM_USER_INITIATE.  0,  0L)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 


//  Uninitialize  DDEML 
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DdeUninitialize  (idlnst)  ; 

return  msg.wParam  ; 

} 

HDDEDATA  FAR  PASCAL  .export  DdeCal 1  back  (UINT  i Type ,  UINT  iFmt,  HCONV  hConv, 

HSZ  hszl ,  HSZ  hsz2,  HDDEDATA  hData, 
DWORD  dwDatal,  DWORD  dwData2) 

{ 

char  szltem  [10],  szPopulation  [16]  ; 
int  i  ; 

switch  ( i Type ) 

{ 

case  XTYP.ADVDATA  :  //  hszl  =  topic 

//  hsz2  =  item 
//  hData  =  data 

//  Check  for  matching  format  and  data  item 

if  (iFmt  !=  CF.TEXT) 

return  DDE.FNOTPROCESSED  ; 

DdeQueryString  (idlnst,  hsz2,  szltem,  sizeof  (szltem),  0)  ; 

for  (1  =  0  ;  i  <  NUM.STATES  ;  1++) 

if  (strcmp  (szltem,  pop[i ] .szAbb)  ==  0) 
break  ; 

if  (i  >=  NUM.STATES) 

return  DDE.FNOTPROCESSED  ; 

//  Store  the  data  and  invalidate  the  window 

DdeGetData  (hData,  szPopulation,  sizeof  (szPopulation),  0)  ; 

pop[i ] . 1  Pop  =  atol  (szPopulation)  ; 

InvalidateRect  (hwnd,  NULL,  FALSE)  ; 

return  DDE.FACK  ; 

case  XTY P.DI SCON NECT  : 
hConv  =  NULL  ; 

MessageBox  (hwnd,  "The  server  has  disconnected.", 
szAppName,  MB.I CONASTERI SK  !  MB.OK)  ; 

return  NULL  ; 
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return  NULL  ; 
} 


long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 


{ 

static  char 

static  short 

char 

HDC 

HSZ 

PAINTSTRUCT 

short 

TEXTMETRIC 


szService  []  =  "DdePop2", 
szTopic  []  =  "US.Population"  ; 
cxChar,  cyChar  ; 
szBuffer  [24]  ; 
hdc  ; 

hszService,  hszTopic,  hszltem  ; 
ps  ; 

i ,  x ,  y  ; 
tm  ; 


switch  (message) 

{ 

case  WM.CREATE  : 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 

cxChar  =  tm.tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm. tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 


return  0  ; 


case  WM_US E R_I N I T I AT E  : 


//  Try  connecting 

hszService  =  DdeCreateStri ngHandle  (idlnst,  szService,  0)  ; 
hszTopic  =  DdeCreateStringHandle  (idlnst,  szTopic,  0)  ; 

hConv  =  DdeConnect  (idlnst,  hszService,  hszTopic,  NULL)  ; 

//  If  that  doesn't  work,  load  server 

if  (hConv  ==  NULL) 

{ 

WinExec  (szService,  SW_SH0WM I NNOACTI VE )  ; 

hConv  =  DdeConnect  (idlnst,  hszService,  hszTopic,  NULL)  ; 
1 


//  Free  the  string  handles 


DdeFreeStringHandle  (idlnst,  hszService)  ; 
DdeFreeStringHandle  (idlnst,  hszTopic)  ; 
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//  If  still  not  connected,  display  message  box 

if  (hConv  ==  NULL) 

{ 

MessageBox  (hwnd,  "Cannot  connect  with  DDEP0P2.EXE!", 
szAppName,  MB_ICONEXC LAMATI ON  !  MB_0K)  ; 


return  0  ; 
} 


//  Request  notification 

for  (1  =  0  ;  i  <  NUM.STATES  ;  1++) 

{ 

hszltem  =  DdeCreateStringHandle  (idlnst,  pop[i].szAbb,  0)  ; 

DdeClientTransaction  (NULL,  0,  hConv,  hszltem,  CF_TEXT, 
XTYP_ADVSTART  !  XTYPF_ACKREQ, 
DDE_TIMEOUT,  NULL)  ; 

DdeFreeStringHandle  (idlnst,  hszltem)  ; 

} 

if  (i  <  NUM_STATES) 

{ 

MessageBox  (hwnd,  "Failure  on  WM_DDE_ADVISE!", 

szAppName,  MB_I CONEXC LAMATI ON  !  MB_0K)  ; 

} 

return  0  ; 
case  WM_PAI NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

for  (i  =  0  ;  i  <  NUM_STATES  ;  i++) 

{ 

if  (i  <  (NUM.STATES  +  1)  /  2) 

{ 

x  =  cxChar  ; 
y  =  i  *  cyChar  ; 

} 

else 

{ 

x  =  44  *  cxChar  ; 

y  =  (i  -  (NUM_STATES  +  1)  /  2)  *  cyChar  ; 

} 
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TextOut  (hdc.  x.  y,  szBuffer, 

wsprintf  (szBuffer,  "%-20s", 

(LPSTR)  pop[i] .szState))  ; 


x  +=  36  *  cxChar  ; 

SetTextAl ign  (hdc,  TA_RIGHT  !  TA_T0P)  ; 

TextOut  (hdc,  x,  y,  szBuffer, 

wsprintf  (szBuffer,  "%101d",  pop[i ] . 1  Pop) )  ; 

SetTextAl ign  (hdc.  TAJ.EFT  !  TA.T0P)  ; 

} 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_C LOSE  : 

if  (hConv  ==  NULL) 
break  ; 


//  Stop  the  advises 

for  (1  =  0  ;  i  <  NUM_STATES  ;  1++) 

{ 

hszltem  =  DdeCreateStringHandle  (idlnst,  pop[i ] .szAbb,  0) 

DdeClientTransaction  (NULL,  0,  hConv,  hszltem,  CFJTEXT, 
XTYP_ADVSTOP,  DDE_TI MEOUT ,  NULL)  ; 

DdeFreeStringHandle  (idlnst,  hszltem)  ; 

} 

//  Disconnect  the  conversation 
DdeDisconnect  (hConv)  ; 
break  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 
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SHOWPOP2.DEF 


SH0WP0P2. DEF  module  definition  file 


NAME  SH0WP0P2 


DESCRIPTION  ' DDEML  Population  Client  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


In  WinMain ,  SHOWPOP2  calls  MakeProclnstance  for  its  call-back  function  (called  Dde¬ 
Callback )  and  passes  the  address  of  the  function  to  Ddelnitialize.  The  DDEML  instance 
handle  is  stored  in  the  global  variable  idlnst,  which  must  be  passed  as  the  first  parameter  to 
all  other  DDEML  function  calls. 

SHOWPOP2  then  sends  itself  a  WM-USER_INITIATE  message;  other  initialization 
occurs  in  the  WndProc  window  procedure.  The  program  calls  DdeCreateStringHandle 
twice  to  create  string  handles  for  the  server’s  service  name  (“DdePop2”)  and  the  topic 
name  (“US -Population”).  SHOWPOP2  passes  these  string  handles  to  DdeConnect  to  at¬ 
tempt  to  initiate  a  conversation  with  the  DDEPOP2  server.  As  in  SHOWPOP1,  if  the  conver¬ 
sation  cannot  be  initiated,  the  program  calls  WinExec  to  load  DDEPOP2  and  then  tries 
again.  Following  this,  the  string  handles  can  be  freed  with  calls  to  DdeFreeStringHandle. 

When  the  DDEPOP2  server  starts  up,  it  calls  Ddelnitialize  in  its  WinMain  function 
and  also  calls  SetTimer  to  set  a  5-second  timer  for  updating  the  population  data.  DDE- 
POP2  then  sends  its  window  procedure  a  WM_USER_INITIATE  message.  While  process¬ 
ing  this  message,  DDEPOP2  initializes  the  population  data  and  creates  two  string  handles 
for  its  service  and  topic  names.  WndProc  then  calls  DdeNameServiceXo  register  its  service 
name.  This  prevents  the  call-back  function  from  receiving  any  connection  requests  that  do 
not  explicitly  name  it  as  a  service. 

When  SHOWPOP2  calls  DdeConnect ,  the  DDE  Management  Library  calls  the  call¬ 
back  function  in  DDEPOP2  with  a  transaction  type  of  XTYP-CONNECT.  The  hszl  and 
hsz2  parameters  to  the  call-back  function  are  string  handles  that  indicate  the  topic  and  ser¬ 
vice  names  passed  to  the  DdeConnect  function.  The  DdeCallback  function  in  DDEPOP2 
uses  the  DdeQueryString  function  to  check  if  the  topic  and  service  names  match  the 
strings  “US -Population”  and  “DdePop2”.  If  the  strings  match,  DdeCallback  returns  TRUE; 
otherwise,  the  function  returns  FALSE.  String  handles  passed  to  a  call-back  function  do  not 
need  to  be  freed  by  the  call-back. 
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When  the  server’s  DdeCallback  function  returns  TRUE  after  processing  the  XTYP- 
_CONNECT  transaction,  the  DDE  conversation  has  begun.  The  DdeConnect  function 
called  by  the  client  (SHOWPOP2)  returns  a  conversation  handle,  which  has  a  data  type  of 
HCONV.  This  handle  is  also  passed  to  the  server’s  call-back  function  in  an  XTYP-CON- 
NECT_CONFIRM  transaction.  The  server  could  save  this  conversation  handle  if  it  wishes, 
but  DDEPOP2  does  not. 

When  we  last  left  SHOWPOP2,  it  had  established  a  connection  with  DDEPOP2  by 
calling  DdeConnect  and  freed  the  string  handles  for  the  service  and  topic  names  required 
for  that  function.  SHOWPOP2  then  attempts  to  begin  hot  links  for  the  populations  of  each 
of  the  50  states,  the  District  of  Columbia,  and  the  entire  United  States.  To  do  this,  SHOW- 
POP2  enters  a  loop  and  calls  DdeCreateStringHandle  for  each  of  the  two-character  state 
codes.  These  are  passed,  along  with  the  conversation  handle,  the  clipboard  format  type, 
and  the  flag  XTYP_ADVSTART  to  DdeClientTransaction.  This  is  the  basic  function  a 
client  uses  to  obtain  data  from  a  server.  Each  string  handle  is  then  freed  with  a  call  to 
DdeFreeStringHandle. 

When  a  client  engaged  in  a  conversation  calls  DdeClientTransaction  with  an  XTYP 
_ADVSTART  parameter,  the  server’s  call-back  function  is  called  by  the  DDE  Management 
Library  with  a  transaction  type  of  XTYP_ADVSTART.  DDEPOP2  simply  checks  if  the  clip¬ 
board  format  is  CF_TEXT  and  the  item  name  is  a  valid  two-character  state  code.  (This  is 
done  in  DDEPOP2’s  GetStateNumber  function.)  If  the  item  name  is  valid,  DDE- 
POP2  then  sets  the  population  of  that  state  to  0  and  posts  a  WM -TIMER  message  to  its  win¬ 
dow  procedure. 

Here’s  where  some  of  the  real  magic  of  DDEML  takes  place.  The  DDEPOP2  server 
has  agreed  to  have  a  conversation,  but  it  has  not  saved  the  conversation  handle.  The 
DDEPOP2  call-back  has  also  received  XTYP-ADVSTART  transactions  for  particular  states, 
but  it  has  not  saved  any  information  about  which  client  in  which  conversation  has  re¬ 
quested  information  about  which  states. 

DDEPOP2  has  not  saved  this  information,  but  the  DDE  Management  Library  has. 
Now  let’s  see  what  happens  when  DDEPOP2  updates  its  population  information  during 
WM-TIMER  (and  WM-TIMECHANGE)  processing  in  WndProc.  It  calls  CalcPops to  calcu¬ 
late  new  populations,  and  then  checks  which  population  changed.  If  a  population  has 
changed,  DDEPOP2  creates  a  string  handle  for  the  two-character  state  code  and  then  calls 
DdePostAdvise  with  the  topic  and  item  names. 

For  each  conversation  where  a  client  has  requested  a  hot  link  with  the  topic  and  item 
names  passed  to  DdePostAdvise ,  DdePostAdvise  calls  DDEPOP2’s  own  call-back  function 
with  an  XTYP-ADVREQ  transaction  type.  The  hszl  and  hsz2  parameters  to  the  call-back 
function  indicate  the  topic  and  item  names.  All  the  call-back  function  needs  do  is  return  a 
data  handle  referencing  the  new  data.  To  do  this,  DdeCallback  formats  the  population  in 
a  string  and  passes  the  string  buffer  to  DdeCreateDataHandle.  This  function  returns  a  data 
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handle  of  type  HDDEDATA,  which  the  call-back  function  simply  returns.  Data  handles 
returned  from  a  call-back  function  do  not  need  to  be  explicitly  freed. 

When  DDEPOP2  returns  a  data  handle  from  its  call-back  function  in  response  to  an 
XTYP_ADVREQ  transaction,  the  DDE  Management  Library  calls  SHOWPOP2’s  call-back 
function  with  a  transaction  type  of  XTYP-ADVDATA.  SHOWPOP2  uses  the  DdeGetData 
function  to  obtain  the  population  data  and  stores  it.  SHOWPOP2  then  invalidates  its  win¬ 
dow  to  update  the  display. 

And  that’s  basically  it.  When  the  time  comes  for  SHOWPOP2  to  terminate,  it  calls 
DdeClientTransaction  for  all  the  states  using  a  transaction  type  of  XTYP_ADVSTOP. 
DDEPOP2  receives  this  transaction  in  its  call-back  function.  SHOWPOP2  then  calls 
DdeDisconnect  and,  after  dropping  out  of  its  message  loop,  DdeDeinitialize.  Any  cleaning 
up  that  the  DDE  programs  failed  to  do  before  this  function  is  done  automatically  by 
DdeDein  i  tial  ize. 
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The  Multiple 
Document 
Interface  (MDI) 


The  Multiple  Document  Interface  (MDI)  is  a  specification  for  applications  that  handle 
documents  in  Microsoft  Windows.  The  specification  describes  a  window  structure  and 
user  interface  that  allow  the  user  to  work  with  multiple  documents  within  a  single  applica¬ 
tion  (such  as  text  documents  in  a  word-processing  program  or  spreadsheets  in  a  spread¬ 
sheet  program).  Simply  put,  just  as  Windows  maintains  multiple  application  windows 
within  a  single  screen,  an  MDI  application  maintains  multiple  document  windows  within 
a  single  client  area.  The  first  MDI  application  for  Windows  was  the  first  Windows  version 
of  Microsoft  Excel.  Both  the  Program  Manager  and  File  Manager  in  Windows  3  are  MDI 
applications. 

Although  the  MDI  specificiation  has  been  around  since  Windows  2,  at  that  time  MDI 
applications  were  difficult  to  write  and  required  some  very  intricate  programming  work. 
With  Windows  3,  however,  much  of  that  work  has  already  been  done  for  you.  Windows  3 
includes  one  new  window  class,  four  new  functions,  two  new  data  structures,  and  eleven 
new  messages  for  the  specific  purpose  of  simplifying  MDI  applications. 
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THE  ELEMENTS  OF  MDI 

The  main  application  window  of  an  MDI  program  is  conventional:  It  has  a  title  bar,  a  menu, 
a  sizing  border,  a  system  menu  icon,  and  minimize/maximize  icons.  The  client  area,  how¬ 
ever,  is  often  called  a  “workspace”  and  is  not  directly  used  to  display  program  output.  This 
workspace  contains  zero  or  more  child  windows,  each  of  which  displays  a  document. 

These  child  windows  look  much  like  normal  application  windows.  They  have  a  title 
bar,  a  sizing  border,  a  system  menu  icon,  minimize/maximize  icons,  and  possibly  scroll 
bars.  None  of  the  document  windows  has  a  menu,  however.  The  menu  on  the  main  applica¬ 
tion  window  applies  to  the  document  windows. 

At  any  one  time,  only  one  document  window  is  active  (indicated  by  a  highlighted 
title  bar)  and  appears  in  front  of  all  the  other  document  windows.  All  the  document  child 
windows  are  clipped  to  the  workspace  area  and  never  appear  outside  the  application 
window. 

At  first,  MDI  seems  a  fairly  straightforward  job  for  the  Windows  programmer.  All  you 
need  to  do  is  create  a  WS_CHILD  window  for  each  document,  making  the  program’s  main 
application  window  the  parent  of  the  document  window.  But  with  a  little  exploration  of  an 
MDI  application  such  as  the  Windows  3  File  Manager,  you’ll  find  some  complications  that 
require  difficult  code. 

■  An  MDI  document  window  can  be  minimized.  Its  icon  appears  at  the 
bottom  of  the  workspace.  (Generally  an  MDI  application  will  use 
different  icons  for  the  main  application  window  and  each  type  of  docu¬ 
ment  window.) 

■  An  MDI  document  window  can  be  maximized.  In  this  case,  the  title  bar  of 
the  document  window  (normally  used  to  show  the  filename  of  the 
document  in  the  window)  disappears,  and  the  filename  appears 
appended  to  the  application  name  in  the  application  window’s  title  bar. 

The  system  menu  icon  of  the  document  window  becomes  the  first  item  in 
the  top-level  menu  of  the  application  window.  The  icon  to  restore  the  size 
of  the  document  window  becomes  the  last  item  in  the  top-level  menu  and 
appears  to  the  far  right. 

■  The  system  keyboard  accelerator  to  close  a  document  window  is  the  same 
as  that  to  close  the  main  window,  except  that  the  Ctrl  key  is  used  rather 
than  Alt.  That  is,  Alt-F4  closes  the  application  window  while  Ctrl-F4 
closes  the  document  window.  In  addition,  Ctrl-F6  switches  among  the 
child  document  windows  within  the  active  MDI  application.  Alt-Spacebar 
invokes  the  system  menu  of  the  main  window,  as  usual.  Alt —  (minus) 
invokes  the  system  menu  of  the  active  child  document  window. 
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■  When  using  the  cursor  keys  to  move  among  items  on  the  menu,  control 
normally  passes  from  the  system  menu  to  the  first  item  on  the  menu  bar. 

In  an  MDI  application,  control  passes  from  the  application  system  menu 
to  the  active  document  system  menu  to  the  first  item  on  the  menu  bar. 

■  If  the  application  is  capable  of  supporting  several  types  of  child  windows 
(for  example,  the  worksheet  and  chart  documents  in  Microsoft  Excel), 
then  the  menu  should  reflect  the  operations  associated  with  that  type  of 
document.  This  requires  that  the  program  change  the  menu  when  a 
different  document  window  becomes  active.  In  addition,  when  no 
document  window  exists,  the  menu  should  be  stripped  down  to  only 
those  operations  involved  in  opening  a  new  document. 

■  The  top-level  menu  bar  has  an  item  called  Window.  By  convention,  this  is 
the  last  item  on  the  top-level  menu  bar  except  for  Help.  The  Window 
submenu  generally  has  options  to  arrange  the  document  windows  within 
the  workspace.  Document  windows  can  be  “cascaded”  from  the  upper 
left  or  “tiled”  so  that  each  document  window  is  fully  visible.  This 
submenu  also  has  a  list  of  all  the  document  windows.  Selecting  one  moves 
that  document  window  to  the  foreground. 

All  of  these  aspects  of  MDI  are  supported  in  Windows  3.  Some  overhead  is  required 
of  course  (as  will  be  shown  in  a  sample  program),  but  it  isn’t  anywhere  close  to  the  amount 
of  code  you’d  have  to  write  to  support  all  these  features  directly. 

WINDOWS  3  AND  MDI 

Some  new  terminology  is  necessary  when  approaching  the  Windows  3  MDI  support.  The 
main  application  window  is  called  the  “frame  window.”  Just  as  in  a  conventional  Windows 
program,  this  is  a  window  of  the  WS_OVERLAPPEDWINDOW  style. 

An  MDI  application  also  creates  a  “client  window”  based  on  the  predefined  window 
class  “MDICLIENT.”  The  client  window  is  created  by  a  call  to  CreateWindow  using  this 
window  class  and  the  WS-CHILD  style.  The  last  parameter  to  CreateWindow  is  a  pointer 
to  a  small  structure  of  type  CLIENTCREATESTRUCT.  This  client  window  covers  the  client 
area  of  the  frame  window  and  is  responsible  for  much  of  the  MDI  support.  The  color  of  this 
client  window  is  the  system  color  COLOR- A PP WORKSPACE. 

The  document  windows  are  called  “child  windows.”  You  create  these  windows  by 
initializing  a  structure  of  type  MDICREATESTRUCT  and  sending  the  client  window  a 
WM-MDICREATE  message  with  a  pointer  to  this  structure. 

The  document  windows  are  children  of  the  client  window,  which  in  turn  is  a  child 
of  the  frame  window.  The  parent-child  hierarchy  is  shown  in  Figure  18-1  on  the  follow¬ 
ing  page. 
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Figure  18-1 .  The  parent-child  hierarchy  of  a  Windows  MDI  application. 

You  need  a  window  class  (and  window  procedure)  for  the  frame  window  and  for  each  type 
of  child  window  supported  by  the  application.  You  don’t  need  a  window  procedure  for  the 
client  window  because  the  window  class  is  preregistered. 

I  mentioned  earlier  that  the  MDI  support  of  Windows  3  includes  one  new  window 
class,  four  new  functions,  two  new  data  structures,  and  eleven  new  messages.  I’ve  already 
mentioned  the  new  window  class,  which  is  MDICLIENT,  and  the  new  data  structures,  CLI- 
ENTCREATESTRUCT  and  MDICREATESTRUCT.  Two  of  the  four  new  functions  replace 
DefWindowProc  in  MDI  applications:  Rather  than  call  DefWindowProc  for  all  unprocessed 
messages,  a  frame  window  procedure  calls  DefFrameProc  and  a  child  window  procedure 
calls  DefMDIChildProc.  Another  new  function,  TranslateMDISysAccel,  is  used  in  the  same 
way  as  TranslateAccelerator ;  which  I  discussed  in  Chapter  9-  The  fourth  new  function  is 
ArrangelconicWindows,  but  one  of  the  special  MDI  messages  makes  this  function  unnec¬ 
essary  for  MDI  programs. 

In  the  sample  program  coming  up,  I’ll  demonstrate  nine  of  the  eleven  MDI  messages. 
(The  other  two  are  not  normally  required.)  These  messages  begin  with  the  prefix  WM- 
_MDI.  A  frame  window  sends  one  of  these  messages  to  the  client  window  to  perform  an 
operation  on  a  child  window  or  to  obtain  information  about  a  child  window.  (For  example, 
a  frame  window  sends  a  WM_MDICREATE  message  to  a  client  window  to  create  a  child 
window.)  The  WM_MDI ACTIVATE  message  is  an  exception:  While  a  frame  window  can 
send  this  message  to  the  client  window  to  activate  one  of  the  child  windows,  the  client 
window  also  sends  the  message  to  the  child  windows  being  activated  and  deactivated  to 
inform  them  of  this  change. 
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THE  SAMPLE  PROGRAM 

The  MDIDEMO  program,  shown  in  Figure  18-2,  demonstrates  the  basics  of  writing  an  MDI 
application. 


MDIDEMO.MAK 

# . - . 

#  MDIDEMO.MAK  make  file 

#  . 

mdidemo.exe  :  mdidemo.obj  mdidemo.def  mdidemo. res 

$(WINLINK)  mdidemo,  mdidemo,  NUL,  $(WINLIB),  mdidemo 
rc  -t  mdidemo. res 

mdidemo.obj  :  mdidemo.c  mdidemo.h 
$(WINCC)  mdidemo.c 

mdidemo. res  :  mdidemo. rc  mdidemo.h 
$ ( WI NRC )  mdidemo. rc 


MDIDEMO.C 

/* .  . 

MDIDEMO.C  --  Multiple  Document  Interface  Demonstration 
(c)  Charles  Petzold,  1992 

. . . - . */ 

#include  <windows.h> 

#include  <stdlib.h> 

#include  "mdidemo.h" 

#define  min(a,b)4  (((a)  <  (b) )  ?  (a)  :  (b) ) 

#define  max(a.b)  (((a)  >  (b) )  ?  (a)  :  (b)) 

long  FAR  PASCAL  .export  FrameWndProc  (HWND,  UINT,  UINT,  LONG)  ; 

BOOL  FAR  PASCAL  .export  Cl oseEnumProc  (HWND,  LONG)  ; 

long  FAR  PASCAL  .export  HelloWndProc  (HWND,  UINT,  UINT,  LONG)  ; 

long  FAR  PASCAL  .export  RectWndProc  (HWND,  UINT,  UINT,  LONG)  ; 

//  structure  for  storing  data  unique  to  each  Hello  child  window 

Figure  18-2.  The  MDIDEMO  program.  (continued) 
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typedef  struct 
{ 

short  nColor  ; 

COLORREF  clrText  ; 

} 

HELLODATA  ; 

typedef  HELLODATA  NEAR  *NPHELLODATA  ; 

//  structure  for  storing  data  unique  to  each  Rect  child  window 

typedef  struct 

{ 

short  cxClient  ; 
short  cyClient  ; 

} 

RECTDATA  ; 


typedef  RECTDATA  NEAR  *NPRECTDATA  ; 

//  global  variables 

char  szFrameClass  []  =  "MdiFrame"  ; 
char  szHelloClass  []  =  "MdiHelloChild"  ; 
char  szRectClass  []  =  "MdiRectChild"  ; 

HANDLE  hlnst  ; 

HMENU  hMenuInit,  hMenuHello,  hMenuRect  ; 

HMENU  hMenuInitWindow,  hMenuHelloWindow,  hMenuRectWindow  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HANDLE  hAccel  ; 

HWND  hwndFrame,  hwndClient  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

hlnst  =  hlnstance  ; 

if  ( JhPrevInstance) 

{ 

//  Register  the  frame  window  class 


wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 


=  CS.HREDRAW  !  CS.VREDRAW  ; 

=  FrameWndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  Loadlcon  (NULL,  I DI_APPLI CATION )  ; 


(continued) 
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wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass.hbrBackground  =  C0L0R__APPW0RKSPACE  +  1  ; 
wndclass.lpszMenuName  =  NULL  ; 
wndclass.lpszClassName  =  szFrameClass  ; 

RegisterClass  (&wndclass)  ; 

//  Register  the  Hello  child  window  class 

wndcl ass. style  =  CS.HREDRAW  !  CSJ/REDRAW  ; 

wndclass.lpfnWndProc  =  HelloWndProc  ; 
wndclass.cbClsExtra  =  0  ; 
wndclass.cbWndExtra  =  sizeof  (LOCALHANDLE)  ; 
wndclass.hlnstance  =  hlnstance  ; 

wndclass.hlcon  =  Loadlcon  (NULL,  IDI_APPLICATION)  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass.hbrBackground  =  GetStockObject  ( WHITE_BRUSH )  ; 
wndclass.lpszMenuName  =  NULL  ; 
wndclass.lpszClassName  =  szHelloClass  ; 

RegisterClass  (&wndclass)  ; 

//  Register  the  Rect  child  window  class 

wndcl ass. style  =  CS_HREDRAW  !  CSJ/REDRAW  ; 

wndclass.lpfnWndProc  =  RectWndProc  ; 
wndclass.cbClsExtra  =  0  ; 
wndclass.cbWndExtra  =  sizeof  (LOCALHANDLE)  ; 
wndclass.hlnstance  =  hlnstance  ; 
wndclass.hlcon  =  NULL  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  IDC_ARR0W)  ; 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
wndclass.lpszMenuName  =  NULL  ; 
wndclass.lpszClassName  =  szRectClass  ; 

RegisterClass  (&wndclass)  ; 

} 

//  Obtain  handles  to  three  possible  menus  &  submenus 

hMenuInit  =  LoadMenu  (hlnst,  "MdiMenuInit")  ; 
hMenuHello  =  LoadMenu  (hlnst,  "MdiMenuHello")  ; 
hMenuRect  =  LoadMenu  (hlnst,  "MdiMenuRect")  ; 

hMenuInitWindow  =  GetSubMenu  (hMenuInit,  INIT_MENU_POS)  ; 
hMenuHelloWindow  =  GetSubMenu  (hMenuHello,  HELL0_MENU_P0S)  ; 
hMenuRectWindow  =  GetSubMenu  (hMenuRect,  RECT_MENU_POS)  ; 

//  Load  accelerator  table 


(continued) 
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hAccel  =  LoadAccelerators  (hlnst,  "MdiAccel")  ; 

//  Create  the  frame  window 

hwndFrame  =  CreateWindow  (szFrameClass,  "MDI  Demonstration”, 

WS_OVERLAPPEDWINDOW  !  WS.CLIPCHILDREN, 
CWJJSEDEFAULT,  CWJJSEDEFAULT, 
CWJJSEDEFAULT,  CW_USEDEFAULT, 

NULL,  hMenuInit ,  hlnstance,  NULL)  ; 

hwndClient  =  GetWindow  (hwndFrame,  GW_CHILD)  ; 

ShowWindow  (hwndFrame,  nCmdShow)  ; 

UpdateWindow  (hwndFrame)  ; 

//  Enter  the  modified  message  loop 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

if  ( ITranslateMDISysAccel  (hwndClient.  &msg)  && 

ITranslateAccelerator  (hwndFrame,  hAccel,  &msg)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

} 

//  Clean  up  by  deleting  unattached  menus 

DestroyMenu  (hMenuHello)  ; 

DestroyMenu  (hMenuRect)  ; 

return  msg.wParam  ; 

} 

long  FAR  PASCAL  .export 
{ 

static  HWND 
CLIENTCREATESTRUCT 
FARPROC 
HWND 

MDICREATESTRUCT 

switch  (message) 

{ 

case  WM.CREATE  :  //  Create  the  client  window 

cl ientcreate.hWindowMenu  =  hMenuInitWindow  ; 
cl i en tc reate. id Fi rstChild  =  I DM_FI RSTCH I LD  ; 


(continued) 


FrameWndProc  (HWND  hwnd, 


hwndClient  ; 
clientcreate  ; 
lpfnEnum  ; 
hwndChild  ; 
mdi create  : 


UINT  message,  UINT  wParam, 
LONG  IParam) 


890 


Chapter  18:  The  Multiple  Document  Interface  (MDI) 


hwndClient  =  CreateWindow  ("MDICLIENT",  NULL. 

WS.CHILD  !  WS_C LI PCHI LDREN  !  WS_VISIBLE, 

0.  0.  0.  0,  hwnd,  1,  hlnst, 

( LPSTR)  &clientcreate)  ; 

return  0  ; 

case  WM_COMMAND  : 
switch  (wParam) 

{ 

case  I DM_NEWH E LLO  :  //  Create  a  Hello  child  window 

mdicreate.szClass  =  szHelloClass  ; 
mdicreate.szTitle  =  "Hello"  ; 
mdi create. hOwner  =  hlnst  ; 
mdicreate.x  =  CW_USEDEFAULT  ; 

mdicreate.y  =  CW_USEDE FAU LT  ; 

mdicreate.cx  =  CW_USEDEFAULT  ; 
mdicreate.cy  =  CW_USEDEFAULT  ; 
mdicreate. style  =  0  ; 
mdicreate.lParam  =  NULL  ; 

hwndChild  =  (HWND)  SendMessage  (hwndClient. 

WM_MD I  CREATE ,  0. 

(long)  (LPMDICREATESTRUCT)  &mdi create)  ; 

return  0  ; 

case  IDM_NEWRECT  :  //  Create  a  Rect  child  window 

mdicreate.szClass  =  szRectClass  ; 
mdicreate.szTitle  =  "Rectangles"  ; 
mdicreate. hOwner  =  hlnst  ; 
mdicreate.x  =  CW_USEDE FAULT  ; 

mdicreate.y  =  CW_USEDE FAU LT  ; 

mdicreate.cx  =  CW_USEDEFAULT  ; 
mdicreate.cy  =  CW_USEDEFAULT  ; 
mdicreate. style  =  0  ; 
mdicreate.lParam  =  NULL  ; 

hwndChild  =  (HWND)  SendMessage  (hwndClient, 

WM_MDI CREATE ,  0. 

(long)  (LPMDICREATESTRUCT)  &mdicreate)  ; 

return  0  ; 

case  I DM_C LOSE  :  //  Close  the  active  window 

hwndChild  =  LOWORD  (SendMessage  (hwndClient, 

WM.MDIGETACTIVE,  0,  0L))  ; 


(continued) 
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if  (SendMessage  (hwndChild,  WM_QUERYENDSESSION,  0.  0L)) 
SendMessage  (hwndClient,  WM_MDI DESTROY , 
hwndChild,  0L)  ; 

return  0  ; 

case  I DM_EX IT  :  //  Exit  the  program 

SendMessage  (hwnd,  WM.CLOSE,  0,  0L)  ; 
return  0  ; 


//  Messages  for  arranging  windows 

case  IDM_TILE  : 

SendMessage  (hwndClient,  WM_MDITILE,  0,  0L)  ; 
return  0  ; 

case  IDM_CASCADE  : 

SendMessage  (hwndClient,  WM_MDICASCADE,  0,  0L)  ; 
return  0  ; 

case  IDM_ARRANGE  : 

SendMessage  (hwndClient.  WM_MDI I CONARRANGE ,  0,  0L)  ; 
return  0  ; 

case  I DM_C LOS EALL  :  //  Attempt  to  close  all  children 

lpfnEnum  =  MakeProcInstance  ((FARPROC)  CloseEnumProc, 

hlnst)  ; 

EnumChildWindows  (hwndClient,  lpfnEnum,  0L)  ; 
FreeProcInstance  (lpfnEnum)  ; 
return  0  ; 

default  :  //  Pass  to  active  child 

hwndChild  =  LOWORD  (SendMessage  (hwndClient, 

WM_MDI GETACTI VE .  0,  0L))  ; 

if  (IsWindow  (hwndChild)) 

SendMessage  (hwndChild,  WM_COMMAND, 
wParam,  IParam)  ; 

break  ;  //  and  then  to  DefFrameProc 

} 

break  ; 

case  WM_QUERY ENDSESS ION  : 

case  WM_CL0SE  :  //  Attempt  to  close  all  children 

SendMessage  (hwnd,  WM.COMMAND,  IDM.CLOSEALL,  0L)  ; 
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892 


Chapter  18:  The  Multiple  Document  Interface  (MDI) 


if  (NULL  !=  GetWindow  (hwndClient,  GW_CHI LD) ) 
return  0  ; 

break  ;  //  ie,  call  DefFrameProc  ; 

case  WM_DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

//  Pass  unprocessed  messages  to  DefFrameProc  (not  DefWindowProc) 

return  DefFrameProc  (hwnd,  hwndClient,  message,  wParam,  IParam)  ; 

} 

BOOL  FAR  PASCAL  .export  Cl oseEnumProc  (HWND  hwnd,  LONG  IParam) 

{ 

if  (GetWindow  (hwnd,  GW.OWNER))  //  check  for  icon  title 

return  1  ; 

SendMessage  (GetParent  (hwnd),  WM_MD I  RESTORE ,  hwnd,  0L)  ; 

if  USendMessage  (hwnd,  WM.QUERYENDSESSION,  0,  0L)) 
return  1  ; 

SendMessage  (GetParent  (hwnd),  WM.MDI DESTROY,  hwnd.  0L)  ; 
return  1  ; 

} 

long  FAR  PASCAL  .export  HelloWndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  COLORREF  clrTextArray  []  =  {  RGB  (0.  0,  0),  RGB  (255,  0,  0), 

RGB  (0,  255,  0),  RGB  (  0,  0,  255), 

RGB  (255,  255,  255)  }  ; 
static  HWND  hwndClient,  hwndFrame  ; 

HDC  hdc  ; 

HMENU  hMenu  ; 

LOCALHANDLE  hHelloData  ; 

NPHELLODATA  npHelloData  ; 

PAINTSTRUCT  ps  ; 

RECT  rect  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

//  Allocate  memory  for  window  private  data 

hHelloData  =  Local A1 1 oc  ( LMEM.MOVEABLE  !  LMEM.ZEROINIT, 

sizeof  (HELLODATA))  ; 
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npHel loData  =  (NPHELLODATA)  LocalLock  (hHelloData)  ; 
npHelloData->nColor  =  IDM_BLACK  ; 
npHelloData->cl rText  =  RGB  (0,  0,  0)  ; 

LocalUnlock  (hHelloData)  ; 

SetWindowWord  (hwnd,  0,  hHelloData)  ; 

//  Save  some  window  handles 

hwndClient  =  GetParent  (hwnd)  ; 
hwndFrame  =  GetParent  (hwndClient)  ; 
return  0  ; 

case  WM_COMMAND  : 
switch  (wParam) 

{ 

case  IDM_BLACK  : 
case  IDM_RED  : 
case  IDM_GREEN  : 
case  IDM_BLUE  : 
case  I DM_WH ITE  : 

//  Change  the  text  color 

hHelloData  =  GetWindowWord  (hwnd,  0)  ; 
npHelloData  =  (NPHELLODATA)  LocalLock  (hHelloData)  ; 

hMenu  =  GetMenu  (hwndFrame)  ; 

CheckMenuItem  (hMenu,  npHelloData->nColor, 

MF_UNCH ECKED )  ; 

npHelloData->nColor  =  wParam  ; 

CheckMenuItem  (hMenu,  npHel 1 oData->nCol or , 
MF.CHECKED)  ; 


npHelloData->clrText  = 

clrTextArray  [wParam  -  IDM_BLACK]  ; 

LocalUnlock  (hHelloData)  ; 

Inval idateRect  (hwnd,  NULL,  FALSE)  ; 

} 

return  0  ; 
case  WM_PAI NT  : 

//  Paint  the  window 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

hHelloData  =  GetWindowWord  (hwnd,  0)  ; 
npHelloData  =  (NPHELLODATA)  LocalLock  (hHelloData)  ; 
SetTextColor  (hdc,  npHel 1 oData->cl rText)  ; 
LocalUnlock  (hHelloData)  ; 
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GetClientRect  (hwnd,  &rect)  ; 

DrawText  (hdc,  "Hello,  World!",  -1,  &rect, 

DT_S INGLELINE  !  DT_C ENTER  !  DTJ/CENTER)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_MDI ACTI VATE  : 

//  Set  the  Hello  menu  if  gaining  focus 
if  (wParam  ==  TRUE) 

SendMessage  (hwndClient,  WM_MDI SETMENU ,  0, 

MAKELONG  (hMenuHello,  hMenuHel loWindow) ) 

//  check  or  uncheck  menu  item 

hHelloData  =  GetWindowWord  (hwnd,  0)  ; 
npHelloData  =  (NPHELLODATA)  LocalLock  (hHelloData)  ; 
CheckMenuItem  (hMenuHello,  npHelloData->nColor, 

wParam  ?  MF.CHECKED  :  MFJJNCHECKED)  ; 
LocalUnlock  (hHelloData)  ; 

//  Set  the  Init  menu  if  losing  focus 

if  (wParam  ==  FALSE) 

SendMessage  (hwndClient,  WM_MDI SETMENU ,  0, 

MAKELONG  (hMenuInit,  hMenuInitWindow) )  ; 

DrawMenuBar  (hwndFrame)  ; 
return  0  ; 

case  WM_QUERYENDSESSION  : 
case  WM_CL0SE  : 

if  ( IDOK  !=  MessageBox  (hwnd,  "OK  to  close  window?",  "Hello", 
MB.ICONQUESTION  !  MB_OKCANCEL) ) 

return  0  ; 

break  ;  //  ie,  call  DefMDIChildProc 

case  WM.DESTROY  : 

hHelloData  =  GetWindowWord  (hwnd,  0)  ; 

LocalFree  (hHelloData)  ; 
return  0  ; 

} 

//  Pass  unprocessed  message  to  DefMDIChildProc 
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return  DefMDIChildProc  (hwnd,  message,  wParam,  IParam)  ; 

} 

long  FAR  PASCAL  .export  RectWndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HWND  hwndClient,  hwndFrame  ; 

HPEN  hBrush  ; 

HDC  hdc  ; 

LOCALHANDLE  hRectData  ; 

NPRECTDATA  npRectData  ; 

PAINTSTRUCT  ps  ; 

short  xLeft,  xRight,  yTop,  yBottom,  nRed,  nGreen,  nBlue  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

//  Allocate  memory  for  window  private  data 

hRectData  =  LocalAlloc  ( LMEM.MOVEABLE  !  LMEM.ZEROINIT, 
sizeof  (RECTDATA) )  ; 

SetWindowWord  (hwnd,  0,  hRectData)  ; 

//  Start  the  timer  going 

SetTimer  (hwnd,  1,  250,  NULL)  ; 

//  Save  some  window  handles 

hwndClient  =  GetParent  (hwnd)  ; 
hwndFrame  =  GetParent  (hwndClient)  ; 
return  0  ; 

case  WM.SIZE  :  //  Save  the  window  size 

hRectData  =  GetWindowWord  (hwnd,  0)  ; 
npRectData  =  (NPRECTDATA)  Local  Lock  (hRectData)  ; 

npRectData->cxClient  =  LOWORD  (IParam)  ; 
npRectData->cyClient  =  HIWORD  (IParam)  ; 

LocalUnlock  (hRectData)  ; 

break  ;  //  WM.SIZE  must  be  processed  by  DefMDIChildProc 

case  WM.TIMER  :  //  Display  a  random  rectangle 

hRectData  =  GetWindowWord  (hwnd,  0)  ; 
npRectData  =  (NPRECTDATA)  Local  Lock  (hRectData)  ; 
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xLeft  =  rand 
xRight  =  rand 
yTop  =  rand 
yBottom  =  rand 
nRed  =  rand 
nGreen  =  rand 
nBlue  =  rand 


0  %  npRectData->cxClient 
0  %  npRectData->cxClient 
0  %  npRectData->cyClient 
0  %  npRectData->cyClient 
0  &  255  ; 

0  &  255  ; 

0  &  255  ; 


hdc  =  GetDC  (hwnd)  ; 

hBrush  =  CreateSol idBrush  (RGB  (nRed,  nGreen,  nBlue))  ; 
SelectObject  (hdc,  hBrush)  ; 

Rectangle  (hdc,  min  (xLeft,  xRight),  min  (yTop,  yBottom), 
max  (xLeft,  xRight),  max  (yTop,  yBottom))  ; 

ReleaseDC  (hwnd,  hdc)  ; 

DeleteObject  (hBrush)  ; 

LocalUnlock  (hRectData)  ; 
return  0  ; 

case  WM_PAI NT  :  //  Clear  the  window 


Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
hdc  =  BeginPaint  (hwnd,  &ps)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_MDI ACTIVATE  :  //  Set  the  appropriate  menu 

if  (wParam  ==  TRUE) 

SendMessage  (hwndClient,  WM_MDI S ETMENU ,  0, 

MAKELONG  (hMenuRect,  hMenuRectWindow) )  ; 

else 

SendMessage  (hwndClient,  WM_MDI SETMENU ,  0, 

MAKELONG  (hMenuInit,  hMenuInitWindow) )  ; 

DrawMenuBar  (hwndFrame)  ; 
return  0  ; 

case  WM.DESTROY  : 

hRectData  =  GetWindowWord  (hwnd,  0)  ; 

Local  Free  (hRectData)  ; 

KillTimer  (hwnd,  1)  ; 
return  0  ; 

} 

//  Pass  unprocessed  message  to  DefMDIChi ldProc 

return  DefMDIChi 1 dProc  (hwnd,  message,  wParam,  IParam)  ; 

} 
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MDIDEMO.RC 

/* .  .  .  - 

MDIDEMO.RC  resource  script 

. . . . */ 


^include  <windows.h> 

#include  "mdidemo.h" 

MdiMenuInit  MENU 

{ 

POPUP  "&File" 

{ 

MENUITEM  "New  &Hello",  IDM_NEWHELLO 

MENUITEM  "New  &Rectangl es",  I DM_NEWRECT 

MENUITEM  SEPARATOR 

MENUITEM  "E&xit".  IDM_EXIT 

} 

} 

MdiMenuHello  MENU 

{ 

POPUP  "&File" 

{ 

MENUITEM  "New  &Hello", 

MENUITEM  "New  &Rectangl es", 

MENUITEM  "&C1 ose", 

MENUITEM  SEPARATOR 
MENUITEM  "E&xit", 

} 

POPUP  "&Color" 

{ 

MENUITEM  "&B1 ack", 

MENUITEM  "&Red", 

MENUITEM  "&Green", 

MENUITEM  "B&lue", 

MENUITEM  "&White", 

} 

POPUP  "&Window" 

{ 

MENUITEM  "&Cascade\tShi ft+F5", 

MENUITEM  "&Tile\tShift+F4", 

MENUITEM  "Arrange  &Icons", 

MENUITEM  "Close  &A11", 

} 

} 


IDM_NEWHELLO 
I DM_NEWRECT 
I DM_C  LOSE 

IDM_EXIT 


I DM_B  LACK 
IDM.RED 
IDM_GREEN 
IDM.BLUE 
I DM_WH I TE 


IDM.CASCADE 
IDM.TILE 
IDM.ARRANGE 
I DM_C  LOSEALL 
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MdiMenuRect  MENU 

{ 

POPUP  "&File" 

{ 

MENUITEM  "New  &Hello", 

MENUITEM  "New  &Rectangl es" , 
MENUITEM  "&Close\ 

MENUITEM  SEPARATOR 
MENUITEM  "E&xit", 

} 

POPUP  "&Window" 

{ 

MENUITEM  "&Cascade\tShift+F5", 
MENUITEM  "&Ti1e\tShift+F4", 
MENUITEM  "Arrange  &Icons". 
MENUITEM  "Close  &A11", 

} 


IDM.NEWHELLO 
I  DM__N  EWRECT 
I DM_C  LOSE 

IDM.EXIT 


IDM.CASCADE 
IDM.TILE 
IDM_ARRANGE 
I DM_C  LOS  EALL 


MdiAccel  ACCELERATORS 

{ 

VK_F5.  IDM_CASCADE,  VIRTKEY ,  SHIFT 
VK_F4,  IDM.TILE,  VIRTKEY ,  SHIFT 
} 


MDIDEMO.H 


/* . . . 

MDIDEMO.H  header  file 

.  . */ 


#define  INIT_MENU_POS  0 
#def i ne  HELL0_MENU_P0S  2 
#define  RECT_MENU_POS  1 

#define  IDM.NEWHELLO  10 
#define  IDM.NEWRECT  11 
#def i ne  IDM.CLOSE  12 
#define  I DM_EX IT  13 

#define  IDM.BLACK  20 
#define  IDM_RED  21 
#define  IDM_GREEN  22 
#define  IDM.BLUE  23 
#define  IDM.WHITE  24 
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#def i ne 

IDM_TILE 

30 

#define  IDM_CASCADE 

31 

♦define 

IDM.ARRANGE 

32 

♦def  i ne 

I DM_C  LOSEALL 

33 

♦define 

IDMJHRSTCHILD 

100 

MDIDEMO.DEF 


MDIDEMO.DEF  module  definition  file 


NAME 


MDIDEMO 


DESCRIPTION  * MDI  Demonstration  (c)  Charles  Petzold,  1992' 

EXETYPE  WINDOWS 

STUB  'WINSTUB.EXE' 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


MDIDEMO  supports  two  types  of  extremely  simple  document  windows:  One  displays 
“Hello,  World!”  in  the  center  of  its  client  area,  and  the  other  displays  a  series  of  random 
rectangles.  (In  the  source  code  listings  and  identifier  names,  these  are  referred  to  as  the 
Hello  document  and  the  Rect  document.)  Different  menus  are  associated  with  these  two 
types  of  document  windows.  The  document  window  that  displays  “Hello,  World!”  has  a 
menu  that  allows  you  to  change  the  color  of  the  text. 

Three  Menus 

Let’s  turn  first  to  the  MDIDEMO. RC  resource  script.  The  resource  script  defines  three  menu 
templates  used  by  the  program. 

The  program  displays  the  MdiMenuInit  menu  when  no  document  windows  are 
present.  This  menu  simply  allows  creating  a  new  document  or  exiting  the  program. 

The  MdiMenuHello  menu  is  associated  with  the  document  window  that  displays 
“Hello,  World!”  The  File  submenu  allows  opening  a  new  document  of  either  type,  closing 
the  active  document,  and  exiting  the  program.  The  Color  submenu  lets  you  set  the  text 
color.  The  Window  submenu  has  options  for  arranging  the  document  windows  in  a 
cascaded  or  tiled  fashion,  arranging  the  document  icons,  and  closing  all  the  windows.  This 
submenu  will  also  list  all  the  document  windows  as  they  are  created. 
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The  MdiMenuRect  menu  is  associated  with  the  random  rectangle  document.  This  is 
the  same  as  the  MdiMenuHello  menu  except  that  it  does  not  include  the  Color  submenu. 

The  MDIDEMO.H  header  file  defines  all  the  menu  identifiers  as  well  as  three 
constants: 

//define  INIT_MENU_POS  0 

//define  HELL0_MENU_P0S  2 

//define  RECT_MENU_POS  1 

These  identifiers  indicate  the  position  of  the  Window  submenu  in  each  of  the  three 
menu  templates.  This  information  is  needed  by  the  program  to  inform  the  client  window 
where  the  document  list  is  to  appear.  Of  course,  the  MdiMenuInit  menu  doesn’t  have  a 
Window  submenu,  so  I’ve  indicated  that  the  list  should  be  appended  to  the  first  submenu 
(position  0).  The  list  will  never  actually  be  viewed  there,  however.  (You’ll  see  why  this  is 
needed  when  I  discuss  the  program  later.) 

The  IDM_FIRSTCHILD  identifier  doesn’t  correspond  to  a  menu  item.  This  is  the 
identifier  that  will  be  associated  with  the  first  document  window  in  the  list  that  will  appear 
in  the  Window  submenu.  This  identifier  should  be  greater  than  all  the  other  menu  IDs. 

Program  Initialization 

In  MDIDEMO.C,  WinMain  begins  by  registering  window  classes  for  the  frame  window 
and  the  two  child  windows.  The  window  procedures  are  called  FrameWndProc,  Hello- 
WndProc ,  and  RectWndProc.  Normally,  different  icons  should  be  associated  with  these 
window  classes.  For  the  purpose  of  simplicity,  I’ve  used  the  standard  I DI -APPLICATION 
icon  for  the  frame  and  child. 

Note  that  I’ve  defined  the  hbrBackground  field  of  the  WNDCLASS  structure  for  the 
frame  window  class  to  be  the  COLOR- A PP WORKSPACE  system  color.  This  is  not  entirely 
necessary  because  the  client  area  of  the  frame  window  is  covered  up  by  the  client  window, 
and  the  client  window  has  this  color  anyway.  However,  using  this  color  looks  a  little  better 
when  the  frame  window  is  first  displayed. 

The  IpszMenuName  field  is  set  to  NULL  for  each  of  these  three  window  classes.  For 
the  Hello  and  Rect  child  window  classes,  this  is  normal.  For  the  frame  window  class  I’ve 
chosen  to  indicate  the  menu  handle  in  the  CreateWindow  function  when  creating  the 
frame  window. 

The  window  classes  for  the  Hello  and  Rect  child  windows  allocate  extra  space  for 
each  window  using  a  nonzero  value  as  the  cbWndExtra  field  of  the  WNDCLASS  structure. 
This  space  will  be  used  to  store  a  local  memory  handle  that  will  reference  a  block  of 
memory  (the  size  of  the  HELLODATA  or  RECTDATA  structures  defined  near  the  top  of 
MDIDEMO.C)  used  to  store  information  unique  to  each  document  window. 
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Next,  WinMain  uses  LoadMenu  to  load  the  three  menus  and  save  their  handles  in 
global  variables.  Three  calls  to  the  GetSubMenu  function  obtain  handles  to  the  Window 
submenu  to  which  the  document  list  will  be  appended.  These  are  also  saved  in  global 
variables.  The  Load  Accelerators  function  loads  the  accelerator  table. 

A  call  to  CreateWindow  in  WinMain  creates  the  frame  window.  During  the  WM- 
_CREATE  processing  in  FrameWndProc ,  the  frame  window  creates  the  client  window. 
This  involves  another  call  to  CreateWindow.  The  window  class  is  set  to  MDICLIENT,  which 
is  the  preregistered  class  for  MDI  client  windows.  The  last  parameter  to  CreateWindow 
must  be  set  to  a  pointer  to  a  structure  of  type  CLIENTCREATESTRUCT.  This  structure  has 
two  fields: 

■  hWindowMenu  is  the  handle  of  the  submenu  to  which  the  document  list 
will  be  appended.  In  MDIDEMO,  this  is  hMenuInitWindow,  which  was 
obtained  during  WinMain.  You’ll  see  later  how  the  menu  is  changed. 

■  idFirstChild  is  the  menu  ID  to  be  associated  with  the  first  document 
window  in  the  document  list.  This  is  simply  IDM_FIRSTCHILD. 

Back  in  WinMain ,  MDIDEMO  displays  the  newly  created  frame  window  and  enters 
the  message  loop.  The  message  loop  differs  a  little  from  a  normal  loop:  After  obtaining  the 
message  from  the  message  queue  with  a  call  to  CetMessage ,  an  MDI  program  passes  the 
message  to  TranslateMDISys Accel  (and  Translate  Accelerator  if,  like  the  MDIDEMO  pro¬ 
gram,  the  program  also  has  menu  accelerators). 

The  TranslateMDISysAccel  function  translates  any  keystrokes  that  may  correspond 
to  the  special  MDI  accelerators  (Ctrl-F6,  for  example)  into  a  WM_SYSCOMMAND  message. 
If  neither  TranslateMDISysAccel  nor  TranslateAccelerator  returns  TRUE  (indicating  that  a 
message  was  translated  by  one  of  these  functions),  do  not  call  TranslateMessage  and 
DispatchMessage. 

Notice  the  two  window  handles  passed  to  TranslateMDISysAccel  and  Translate- 
Accelerator.  hwndClient  and  hwndFrame,  respectively.  The  WinMain  function  obtains 
the  hwndClient  window  handle  by  calling  GetWindow  with  the  GW_CHILD  parameter. 

CREATING  THE  CHILDREN 

The  bulk  of  FrameWndProc  is  devoted  to  processing  WM_COMMAND  messages  that  sig¬ 
nal  menu  selections.  As  usual,  the  wParam  parameter  to  FrameWndProc  contains  the 
menu  ID  number. 

For  wParam  values  of  IDM-NEWHELLO  and  IDM-NEWRECT,  FrameWndProc 
must  create  a  new  document  window.  This  involves  initializing  the  fields  of  an 
MDICREATESTRUCT  structure  (most  of  which  correspond  to  CreateWindow  parameters) 
and  sending  the  client  window  a  WM_MDICREATE  message  with  iParam  set  to  a  pointer 
to  this  structure.  The  client  window  then  creates  the  child  document  window. 
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Normally  the  szTitle  field  of  the  MDICREATESTRUCT  structure  would  be  the  file¬ 
name  corresponding  to  the  document.  The  style  field  can  be  set  to  the  window  styles 
WS_HSCROLL  or  WS-VSCROLL  or  both  to  include  scroll  bars  in  the  document  window. 
(Under  Windows  3.0,  you  must  call  ShowScrollBar  after  creating  the  window  to  display  the 
scroll  bars.  This  is  not  necessary  in  Windows  3.1.)  The  style  field  can  also  include  WS- 
-MINIMIZE  or  WS_MAXIMIZE  to  initially  display  the  document  window  in  a  minimized 
or  maximized  state. 

The  iParam  field  of  the  MDICREATESTRUCT  structure  provides  a  way  for  the  frame 
window  and  the  child  window  to  share  some  variables.  This  field  could  be  set  to  a  local  or 
global  memory  handle  that  references  a  block  of  memory  containing  a  structure.  During 
the  WM_CREATE  message  in  the  child  document  window,  IParam  is  a  pointer  to  a 
CREATESTRUCT  structure,  and  the  IpCreateParams  field  of  this  structure  is  a  pointer  to 
the  MDICREATESTRUCT  structure  used  to  create  the  window. 

On  receipt  of  the  WM_MDICREATE  message,  the  client  window  creates  the  child 
document  window  and  adds  the  title  of  the  window  to  the  bottom  of  the  submenu  speci¬ 
fied  in  the  MDICLIENTSTRUCT  structure  used  to  create  the  client  window.  When  the 
MDIDEMO  program  creates  its  first  document  window,  this  is  the  File  submenu  of  the 
MdiMenuInit  menu.  We’ll  see  later  how  this  document  list  gets  moved  to  the  Window  sub¬ 
menu  of  the  MdiMenuHello  and  MdiMenuRect  menus. 

Up  to  nine  documents  can  be  listed  on  the  menu,  each  preceded  by  an  underlined 
number  from  1  to  9.  If  more  than  nine  document  windows  are  created,  this  list  is  followed 
by  a  “More  windows”  item  on  the  menu.  This  item  invokes  a  dialog  box  with  a  list  box  that 
lists  all  the  document  windows.  The  maintenance  of  this  document  list  is  one  of  the  nicest 
features  of  the  Windows  3  MDI  support. 

MORE  FRAME  WINDOW  MESSAGE  PROCESSING 

Let’s  continue  with  FrameWndProc  message  processing  before  turning  our  attention  to  the 
child  document  windows. 

When  you  select  Close  from  the  File  menu,  MDIDEMO  closes  the  active  child  win¬ 
dow.  It  obtains  the  handle  to  the  active  child  window  by  sending  the  client  window  a 
WM_MDIGETACTIVE  message.  If  the  child  window  responds  affirmatively  to  a  WM- 
_QUERYENDSESSION  message,  then  MDIDEMO  sends  the  client  window  a  WM_MDI- 
DESTROY  message  to  close  the  child  window. 

Processing  the  Exit  option  from  the  File  menu  requires  only  that  the  frame  window 
procedure  send  itself  a  WM -CLOSE  message. 

Processing  the  Tile,  Cascade,  and  Arrange  Icons  options  from  the  Window  submenu 
is  a  snap,  requiring  only  that  the  WM-MDITILE,  WM-MDICASCADE,  and  WM-MDI- 
ICONARRANGE  messages  be  sent  to  the  client  window. 
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The  Close  All  option  is  a  little  more  complex.  FrameWndProc  calls  EnumChildWin- 
dows ,  passing  a  pointer  referencing  the  CloseEnumProc  function.  This  function  sends  a 
WM-MDIRESTORE  message  to  each  child  window,  followed  by  a  WM_QUERYENDSES- 
SION  and  (possibly)  a  WM-MDIDESTROY  message.  This  is  not  done  for  the  icon  title  win¬ 
dow,  indicated  by  a  non-NULL  return  of  GetWindow  with  the  GW_OWNER  parameter. 

You’ll  notice  that  FrameWndProc  does  not  process  any  of  the  WM_COMMAND  mes¬ 
sages  that  signal  one  of  the  colors  being  selected  from  the  Color  menu.  These  messages  are 
really  the  responsibility  of  the  document  window.  For  this  reason,  FrameWndProc  sends 
all  unprocessed  WM_COMMAND  messages  to  the  active  child  window  so  that  the  child 
window  can  process  those  messages  that  pertain  to  its  window. 

All  messages  that  the  frame  window  procedure  chooses  not  to  process  must  be 
passed  to  DefFrameProc.  This  is  one  of  the  new  MDI  functions.  It  replaces  DefWin- 
dowProc  in  the  frame  window  procedure.  Even  if  a  frame  window  procedure  traps  the 
WM_MENUCHAR,  WM_SETFOCUS,  or  WM_SIZE  messages,  these  also  must  be  passed  to 
DefFrameProc. 

Unprocessed  WM_COMMAND  messages  must  also  be  passed  to  DefFrameProc.  In 
particular,  FrameWndProc  does  not  process  any  of  the  WM_COMMAND  messages  result¬ 
ing  from  the  user  selecting  one  of  the  documents  from  the  list  in  the  Window  submenu. 
(The  wParam  values  for  these  options  begin  with  IDM_FIRSTCHILD.)  These  messages 
are  passed  to  DefFrameProc  and  processed  there. 

Notice  that  the  frame  window  does  not  need  to  maintain  a  list  of  window  handles  of 
all  document  windows  it  creates.  If  ever  these  handles  are  needed  (such  as  when  process¬ 
ing  the  Close  All  option  from  the  menu),  they  can  be  obtained  using  EnumChildWindows. 

THE  CHILD  DOCUMENT  WINDOWS 

Now  let’s  look  at  HelloWndProc,  which  is  the  window  procedure  used  for  the  child  docu¬ 
ment  windows  that  display  “Hello,  World!” 

As  with  any  window  class  used  for  more  than  one  window,  static  variables  defined  in 
the  window  procedure  (or  any  function  called  from  the  window  procedure)  are  shared  by 
all  windows  created  based  on  that  window  class. 

Data  that  is  unique  to  each  window  must  be  stored  using  a  method  other  than  static 
variables.  One  such  technique  involves  window  properties.  Another  approach  (the  one  I 
used)  uses  memory  space  reserved  by  defining  a  nonzero  value  in  the  cbWndExtra  field  of 
the  WNDCLASS  structure  used  to  register  the  window  class. 

In  MDIDEMO,  I  use  this  space  to  store  a  local  memory  handle  that  references  a  block 
of  memory  the  size  of  the  HELLODATA  structure.  HelloWndProc  allocates  this  memory 
during  the  WM_CREATE  message,  locks  it,  initializes  the  two  fields  (which  indicate  the 
currently  checked  menu  item  and  the  text  color),  unlocks  the  block,  and  stores  the  local 
memory  handle  using  SetWindowWord. 
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When  processing  a  WM_COMMAND  message  for  changing  the  text  colors  (recall 
that  these  messages  originate  in  the  frame  window  procedure),  HelloWndProc  uses  Get- 
WindowWord  to  obtain  a  handle  to  the  memory  block  containing  the  HELLODATA  struc¬ 
ture.  Using  this  structure,  HelloWndProc  unchecks  the  checked  menu  item,  checks  the 
selected  menu  item,  and  saves  the  new  color. 

A  document  window  procedure  receives  the  WM_MDI ACTIVATE  message  when¬ 
ever  the  window  becomes  active  or  inactive  (indicated  by  a  TRUE  or  FALSE  value  in 
wParam).  You’ll  recall  that  the  MDIDEMO  program  has  three  different  menus:  Mdi- 
Menulnit  for  when  no  documents  are  present,  MdiMenuHello  for  when  a  Hello  document 
window  is  active,  and  MdiMenuRect  for  when  a  Rect  document  window  is  active. 

The  WM_MDI ACTIVATE  message  provides  an  opportunity  for  the  document  win¬ 
dow  to  change  the  menu.  If  wParam  is  TRUE  (meaning  the  window  is  becoming  active), 
HelloWndProc  changes  the  menu  to  MdiMenuHello.  If  wParam  is  FALSE,  HelloWndProc 
changes  the  menu  to  MdiMenuInit. 

HelloWndProc  changes  the  menu  by  sending  a  WM_MDISETMENU  message  to  the 
client  window.  The  client  window  processes  this  message  by  removing  the  document  list 
from  the  current  menu  and  appending  it  to  the  new  menu.  This  is  how  the  document  list  is 
transferred  from  the  MdiMenuInit  menu  (which  is  in  effect  when  the  first  document  is  cre¬ 
ated)  to  the  MdiMenuHello  menu.  Do  not  use  the  SetMenu  function  to  change  a  menu  in  an 
MDI  application. 

Another  little  chore  involves  the  checkmarks  on  the  Color  submenu.  Program  op¬ 
tions  such  as  this  should  be  unique  to  each  document.  For  example,  you  should  be  able  to 
set  black  text  in  one  window  and  red  text  in  another.  The  menu  checkmarks  should  reflect 
the  option  chosen  in  the  active  window.  For  this  reason,  HelloWndProc  unchecks  the  se¬ 
lected  menu  item  when  the  window  is  becoming  inactive  and  checks  the  appropriate  item 
when  the  window  is  becoming  active. 

The  window  procedure  gets  the  first  WM_MDI ACTIVATE  message  with  wParam  set 
to  TRUE  when  the*  window  is  first  created  and  gets  the  last  message  with  wParam  set  to 
FALSE  when  the  window  is  destroyed.  When  the  user  switches  from  one  document  to  an¬ 
other,  the  first  document  window  receives  a  WM_MDIACTIVATE  message  with  wParam 
set  to  FALSE  (at  which  time  it  sets  the  menu  to  MdiMenuInit)  and  the  second  document 
window  receives  a  WM_MDI ACTIVATE  message  with  wParam  set  to  TRUE  (at  which  time 
it  sets  the  menu  to  MdiMenuHello  or  MdiMenuRect  as  appropriate).  If  all  the  windows  are 
closed,  the  menu  is  left  as  MdiMenuInit. 

You’ll  recall  that  FrameWndProc  sends  the  child  window  a  WM_QUERYENDSES- 
SION  message  when  the  user  selects  Close  or  Close  All  from  the  menu.  HelloWndProc  pro¬ 
cesses  the  WM_QUERYENDSESSION  and  WM-CLOSE  messages  by  displaying  a  message 
box  and  asking  the  user  whether  the  window  can  be  closed.  (In  a  real  program,  this  mes¬ 
sage  box  would  ask  whether  a  file  needed  to  be  saved.)  If  the  user  indicates  that  the  win¬ 
dow  should  not  be  closed,  the  window  procedure  returns  0. 
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During  the  WM -DESTROY  message,  HelloWndProc  frees  the  local  memory  block 
allocated  during  the  WM -CREATE  message. 

All  unprocessed  messages  must  be  passed  on  to  DefMDIChildProc  (not  DefWin- 
dowProc )  for  default  processing.  Several  messages  must  be  passed  to  DefMDIChildProc 
whether  the  child  window  procedure  does  something  with  them  or  not.  These  are: 
WM-CHILDACTIVATE,  WM-GETMINMAXINFO,  WM-MENUCHAR,  WM-MOVE,  WM- 
-SETFOCUS,  WM-SIZE,  and  WM-SYSCOMMAND. 

RectWndProc  is  fairly  similar  to  HelloWndProc  in  much  of  the  overhead  involved, 
but  it’s  a  little  simpler  (no  menu  options  are  involved  and  the  window  does  not  verify  with 
the  user  whether  it  can  be  closed),  so  I  needn’t  discuss  it.  But  note  that  RectWndProc 
breaks  after  processing  WM-SIZE  so  it  is  passed  to  DefMDIChildProc. 

CLEANING  UP 

In  WinMain ,  MDIDEMO  uses  LoadMenu  to  load  the  three  menus  defined  in  the  resource 
script.  Normally  Windows  will  destroy  a  menu  at  the  time  the  window  to  which  the  menu  is 
attached  is  destroyed.  That  takes  care  of  the  Init  menu.  However,  menus  that  are  not  at¬ 
tached  to  a  window  (in  MDIDEMO,  the  Hello  and  Rect  menus)  will  continue  to  occupy 
valuable  space  in  memory,  even  after  the  program  terminates.  For  this  reason,  MDIDEMO 
calls  DestroyMenu  twice  at  the  end  of  WinMain  to  get  rid  of  the  Hello  and  Rect  menus. 

THE  POWER  OF  WINDOW  PROCEDURE 

Much  of  the  support  in  Windows  3  for  the  Multiple  Document  Interface  is  encapsulated  in 
the  MDICLIENT  window  class.  I  think  this  clearly  illustrates  the  power  of  the  object- 
oriented  architecture  of  Windows.  The  client  window  procedure  serves  as  an  intermediary 
layer  between  the  frame  window  and  the  various  document  windows. 

Now  let’s  look  at  another  powerful  feature  of  Windows — dynamic  link  libraries. 
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Dynamic  link  libraries  (also  called  DLLs,  dynamic  libraries,  “dynalink”  libraries,  or  library 
modules)  are  one  of  the  most  important  structural  elements  of  Windows.  Most  of  the  disk 
files  associated  with  Windows  are  either  program  modules  or  dynamic  link  library  mod¬ 
ules.  So  far  we’ve  been  writing  Windows  programs;  now  it’s  time  to  take  a  stab  at  writing 
dynamic  link  libraries.  Many  of  the  principles  you’ve  learned  in  writing  programs  are  also 
applicable  to  writing  these  libraries,  but  there  are  some  important  differences. 


LIBRARY  BASICS 

As  you’ve  seen,  a  Windows  program  is  an  executable  file  that  generally  creates  one  or 
more  windows  and  uses  a  message  loop  to  receive  user  input.  Dynamic  link  libraries  are 
generally  not  directly  executable,  and  they  do  not  receive  messages.  They  are  separate 
files  containing  functions  that  can  be  called  by  programs  and  other  DLLs  to  perform  cer¬ 
tain  jobs.  A  dynamic  link  library  is  brought  into  action  only  when  another  module  calls  one 
of  the  functions  in  the  library. 

The  term  dynamic  linking  refers  to  the  process  that  Windows  uses  to  link  a  function 
call  in  one  module  to  the  actual  function  in  the  library  module.  “Static  linking”  occurs 
when  you  run  LINK  or  TLINK  to  create  a  Windows  .EXE  file  from  various  object  (.OBJ) 
modules  and  run  time  library  (.LIB)  files.  Dynamic  linking  occurs  at  run  time. 
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KRNLx86.EXE,  USER.EXE,  and  GDI.EXE  files,  the  various  driver  files  such  as  KEY- 
BOARD.DRV,  SYSTEM. DRV,  and  MOUSE. DRV,  and  the  video  and  printer  drivers  are  all 
dynamic  link  libraries.  These  are  libraries  that  all  Windows  programs  can  use. 

The  various  font  resource  files  with  the  extension  .FON  are  “resource-only”  dynamic 
link  libraries.  They  contain  no  code  and  no  data  but  instead  have  fonts  that  all  Windows 
programs  can  use.  Thus,  one  purpose  of  dynamic  link  libraries  is  to  provide  functions  and 
resources  that  can  be  used  by  many  different  programs.  In  a  conventional  operating  sys¬ 
tem,  only  the  operating  system  itself  contains  routines  that  other  programs  can  call  on  to 
do  a  job.  In  Windows,  the  process  of  one  module  calling  a  function  in  another  module  is 
generalized.  In  effect,  by  writing  a  dynamic  link  library,  you  are  writing  an  extension  to 
Windows.  Or  you  can  think  of  dynamic  link  libraries  (including  those  that  make  up  Win¬ 
dows)  as  extensions  to  your  program.  The  code,  data,  and  resources  in  a  dynamic  link 
library  module  are  shared  among  all  programs  using  the  module. 

Although  a  dynamic  link  library  module  may  have  any  extension  (such  as  .EXE  or 
.FON),  the  standard  extension  in  Windows  3  is  .DLL.  Only  dynamic  link  libraries  with  the 
extension  .DLL  will  be  loaded  automatically  by  Windows.  If  the  file  has  another  extension, 
the  program  must  explicitly  load  the  module  using  the  LoadLibrary  function. 

You’ll  generally  find  that  dynamic  libraries  make  most  sense  in  the  context  of  a  large 
application.  For  instance,  suppose  you  write  a  large  accounting  package  for  Windows  that 
consists  of  several  different  programs.  You’ll  probably  find  that  these  programs  use  many 
common  routines.  You  could  put  these  common  routines  in  a  normal  object  library  (with 
the  extension  .LIB)  and  add  them  to  each  of  the  program  modules  during  static  linking 
with  LINK.  But  this  approach  is  wasteful,  because  each  of  the  programs  in  this  package 
contains  identical  code  for  the  common  routines.  Moreover,  if  you  change  one  of  these  rou¬ 
tines  in  this  library,  you’ll  have  to  relink  all  the  programs  that  use  the  changed  routine.  If, 
however,  you  put  these  common  routines  in  a  dynamic  link  library  called  (for  instance) 
ACCOUNT.DLL,  you’ve  solved  both  problems.  Only  the  library  module  need  contain  the 
routines  required  by  all  the  programs  (thus  requiring  less  disk  space  for  the  files  and  less 
memory  space  when  running  two  or  more  of  the  applications  simultaneously),  and  you  can 
make  changes  to  the  library  module  without  relinking  any  of  the  individual  programs. 

Dynamic  link  libraries  can  themselves  be  viable  products.  For  instance,  suppose  you 
write  a  collection  of  three-dimensional  drawing  routines  and  put  them  in  a  dynamic  link 
library  called  GDI3.DLL.  If  you  then  interest  other  software  developers  in  using  your 
library,  you  can  license  it  to  be  included  with  their  graphics  programs.  A  user  who  has 
several  of  these  programs  would  need  only  one  GDI3.DLL  file. 

Library:  One  Word,  Many  Meanings 

Part  of  the  confusion  surrounding  dynamic  link  libraries  results  from  the  appearance  of 
the  word  library  in  several  different  contexts.  Besides  dynamic  link  libraries,  we’ll  also  be 
talking  about  “object  libraries”  and  “import  libraries.” 
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An  object  library  is  a  file  with  the  extension  .LIB  containing  code  that  is  added  to 
your  program’s  .EXE  file  when  you  run  the  linker  during  static  linking.  For  example,  the 
normal  C  runtime  object  library  that  you  link  with  small-model  Windows  programs  is 
SLIBCEW.LIB  for  the  Microsoft  compiler  and  CWS.LIB  for  the  Borland  compiler. 

An  import  library  is  a  special  form  of  an  object  library  file.  Like  object  libraries,  import 
libraries  have  the  extension  .LIB  and  are  used  by  the  linker  to  resolve  function  calls  in  your 
source  code.  However,  import  libraries  contain  no  code.  Instead,  they  provide  the  linker  with 
information  necessary  to  set  up  relocation  tables  within  the  .EXE  file  for  dynamic  linking.  The 
LIBW.LIB  included  with  the  Microsoft  compiler  and  IMPORT.LIB  included  with  the  Borland 
compiler  are  import  libraries  for  Windows  functions.  If  you  call  Rectangle  in  a  program, 
LIBW.LIB  tells  LINK  that  this  function  is  in  the  GDI. EXE  library  and  has  an  “ordinal  number” 
of  27.  This  information  goes  into  the  .EXE  file  so  that  Windows  can  perform  dynamic  link¬ 
ing  with  the  GDI. EXE  dynamic  link  library  when  your  program  is  executed. 

Object  libraries  and  import  libraries  are  used  only  during  program  development. 
Dynamic  link  libraries  are  used  during  run  time.  A  dynamic  library  must  be  present  on  the 
disk  when  a  program  is  run  that  uses  the  library.  When  Windows  needs  to  load  a  dynamic 
link  library  module  before  running  a  program  that  requires  it,  the  library  file  must  be 
stored  in  either  the  current  directory,  a  directory  accessible  through  the  PATH  string 
in  the  MS-DOS  environment,  the  Windows  directory,  or  the  SYSTEM  subdirectory  of  the 
Windows  directory. 

Examining  Libraries  with  EXEHDR 

Both  program  files  and  dynamic  link  library  files  are  in  the  New  Executable  format.  You 
can  get  some  sense  of  the  workings  of  dynamic  linking  by  running  the  EXEHDR  program 
(included  with  Microsoft  C/C++  7)  with  the  -v  (verbose)  parameter  on  the  various  files  in¬ 
cluded  with  Windows  and  seeing  what  type  of  information  the  files  contain.  (The  TDUMP 
program  included  with  the  Borland  compiler  is  similar  to  EXEHDR.)  EXEHDR  divides  its 
output  into  five  main  sections,  in  this  order: 

■  The  old  MS-DOS  .EXE  header  information 

■  The  New  Executable  format  header  information 

■  A  list  of  the  code  and  data  segments  in  the  module 

■  The  exported  functions  of  the  module 

■  Relocation  information  for  each  segment 

Some  of  this  information  won’t  be  present  for  resource-only  library  modules  (such  as  the 
.FON  files).  You’ll  notice  that  the  first  line  of  the  second  section  begins  with  either 
“Module,”  indicating  a  program  module,  or  “Library,”  indicating  a  dynamic  link  library. 

If  you  run  EXEHDR  on  KRNL286.EXE,  KRNL386.EXE,  USER.EXE,  or  GDI. EXE,  you’ll 
find  that  many  of  the  names  of  the  exported  functions  (the  fourth  section  of  the  output)  are 
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familiar.  These  are  the  functions  that  the  library  makes  available  for  other  modules  to  call. 
Each  exported  function  has  an  “ordinal  number”  associated  with  it.  This  is  simply  a  posi¬ 
tive  number  in  the  “ord”  column  of  the  EXEHDR  output. 

Both  program  modules  and  library  modules  can  call  functions  that  are  exported  from 
other  library  modules.  To  the  module  that  makes  the  call,  the  function  is  said  to  be  “im¬ 
ported.”  These  imported  functions  show  up  in  the  last  section  of  the  EXEHDR  display  as 
relocation  items,  generally  in  the  form  of  the  library  module  name  followed  by  a  period 
and  the  ordinal  number  of  the  function. 

When  Windows  loads  a  program  into  memory  for  execution,  it  must  resolve  the  calls 
that  the  program  makes  to  imported  functions.  If  the  library  module  containing  these  func¬ 
tions  has  not  yet  been  loaded  into  memory,  Windows  loads  at  least  the  data  segment  and 
one  code  segment  into  memory  and  calls  a  short  initialization  routine  in  the  library  mod¬ 
ule.  Windows  also  creates  “reload  thunks”  (a  topic  discussed  in  Chapter  7)  for  the  exported 
functions  in  the  library.  The  calls  in  the  program  to  external  functions  can  then  be  resolved 
by  inserting  the  addresses  of  the  reload  thunks  in  the  code  segment  of  the  program. 

The  second  section  of  the  EXEHDR  output  points  up  some  differences  between 
programs  and  libraries.  Windows  programs  have  a  line  that  reads: 

Data:  NOSHARED 

This  means  that  new  data  segments  are  created  for  each  instance  of  the  program.  Because 
a  single  instance  of  a  Windows  library  is  shared  by  all  programs  that  need  it,  this  line  is 
different  for  Windows  libraries.  It  can  be  either: 

Data:  SHARED 

or: 

Data:  NONE 

depending  on  whether  the  library  has  one  data  segment  or  none. 

A  Windows  program  must  have  at  least  one  data  segment  (called  the  automatic  data 
segment),  because  this  data  segment  contains  the  program’s  stack.  In  the  EXEHDR  output 
of  a  program  file,  you’ll  see  an  indication  of  the  stack  size  (“Extra  Stack  Allocation”).  How¬ 
ever,  a  library  module  doesn’t  have  its  own  stack,  and  thus  EXEHDR  won’t  show  this  line. 
A  dynamic  link  library  always  uses  the  stack  of  the  program  that  calls  the  functions  in 
the  library.  The  absence  of  a  stack  for  the  library  module  has  some  significant  implications 
that  I’ll  cover  later  in  this  chapter. 

Because  each  Windows  program  has  its  own  stack,  Windows  must  switch  between 
stacks  when  switching  from  one  program  to  another.  A  stack’s  presence  in  a  program  iden¬ 
tifies  the  program  as  a  distinct  process  that  can  receive  messages  from  Windows.  A  library 
module  is  not  a  process  and  does  not  receive  messages.  When  a  program  calls  a  function  in 
a  library  module,  no  task  switch  takes  place.  To  Windows,  the  program  making  the  call  to 
the  library  is  still  running  even  though  code  in  the  library  is  being  executed. 
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STRPROG  AND  STRLIB 

We’ll  begin  by  writing  a  program  with  a  dedicated  dynamic  link  library  and  see  how  they 
work  together.  The  program  is  called  STRPROG  (“string  program”),  and  the  dynamic  link 
library  is  called  STRLIB  (“string  library”).  STRLIB  has  three  exported  functions  that 
STRPROG  calls.  Just  to  make  this  interesting  (and  to  force  you  to  think  about  some  of 
the  implications),  one  of  the  functions  in  STRLIB  uses  a  call-back  function  defined  in 
STRPROG. 

STRLIB  is  a  dynamic  link  library  module  that  stores  and  sorts  up  to  256  character 
strings.  The  strings  are  capitalized  and  stored  in  STRLIB’s  own  data  segment.  STRPROG 
can  use  STRLIB’s  three  functions  to  add  strings,  delete  strings,  and  obtain  all  the  current 
strings  from  STRLIB.  The  program  has  two  menu  items  (Enter  and  Delete)  that  invoke 
dialog  boxes  to  add  and  delete  these  strings.  STRPROG  lists  all  the  current  strings 
stored  in  STRLIB’s  data  segment  in  STRPROG’s  client  area. 

This  function  defined  in  STRLIB  adds  a  string  to  STRLIB’s  data  segment: 

BOOL  FAR  PASCAL  _export  AddString  (lpStringln) 

The  parameter  IpString  is  a  far  pointer  to  the  string.  The  string  is  capitalized  within  the 
AddString  function.  If  an  identical  string  already  exists  in  STRLIB’s  data  segment,  this 
function  adds  another  copy  of  the  string.  AddString  returns  TRUE  (nonzero)  if  it  is  suc¬ 
cessful  and  FALSE  (0)  otherwise.  A  FALSE  return  value  can  result  if  the  string  has  a  length  of 
0,  if  memory  could  not  be  allocated  to  store  the  string,  or  if  256  strings  are  already  stored. 
This  STRLIB  function  deletes  a  string  from  STRLIB’s  data  segment: 

BOOL  FAR  PASCAL  .export  Del eteSt ri ng  (lpStringln) 

Again,  the  parameter  IpString  is  a  far  pointer  to  the  string.  If  more  than  one  string  matches, 
only  the  first  is  removed.  DeleteString  returns  TRUE  (nonzero)  if  it  is  successful  and  FALSE 
(0)  otherwise.  A  FALSE  return  value  indicates  that  the  length  of  the  string  is  0  or  that  a 
matching  string  could  not  be  found. 

This  STRLIB  function  uses  a  call-back  function  located  in  the  calling  program  to 
enumerate  the  strings  currently  stored  in  STRLIB’s  data  segment: 

short  FAR  PASCAL  .export  GetStrings  (1 pfnGetStrCal 1  Back,  IpParam) 

The  call-back  function  must  be  defined  as  follows: 

BOOL  FAR  PASCAL  .export  GetStrCal 1  Back  (LPSTR  IpString,  LPVOID  IpParam) 

The  GetStrCallBack  function  must  be  exported  from  the  program  that  calls  GetStrings. 
The  IpfnGetStrCallBack  parameter  to  GetStrings  must  be  obtained  from  MakeProcIn- 
stance.  GetStrings  calls  GetStrCallBack  once  for  each  string  or  until  the  call-back  function 
returns  FALSE  (0).  GetStrings  returns  the  number  of  strings  passed  to  the  call-back  func¬ 
tion.  The  IpParam  parameter  is  a  far  pointer  to  programmer-defined  data.  Note  that  all  the 
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pointers  passed  as  function  parameters  are  far  pointers,  because  STRLIB  must  reference 
data  in  the  caller’s  data  segment. 

Just  as  all  functions  in  a  program  that  are  called  from  outside  the  program  must  be 
exported  using  the  -export  keyword,  all  functions  located  in  a  dynamic  link  library  that 
are  available  for  calling  from  a  program  or  another  dynamic  link  library  must  also  be 
exported. 

Make  File  Differences 

Compiling  dynamic  link  libraries  requires  slightly  different  compilation  options,  and  link¬ 
ing  requires  different  object  libraries.  For  this  reason,  Figures  19-1  and  19-2  show  two  addi¬ 
tional  batch  files,  similar  to  those  in  Chapter  1,  that  set  environment  variables  for  the 
Microsoft  C/C++  7.0  and  Borland  C++  3.1  compilers  for  use  in  make  files. 

MSCDLL.BAT 

REM  . - . 

REM  MSCDLL.BAT  --  Set  up  environment  for  Microsoft  C  7.0  NMAKE 

REM  .  . 

SET  DLLCC=cl  -c  -ASw  -G2sw  -Ow  -W3  -Zp  -Tp 
SET  DLLLINK=1 ink  /nod  libentry 
SET  DLLLI B=sdl 1 cew  oldnames  libw 
SET  DLLRC=rc  -r 

Figure  19-1 .  The  MSCDLL.BAT file  for  using  the  Microsoft  C/C++  7.0  Compiler. 


BCPDLL.BAT 

REM  .  . 

REM  BCPDLL.BAT  --  Set  up  environment  for  Borland  C++  3.0  MAKE 

REM  .  . 

SET  DLLCC=bcc  -c  -ms!  -w-par  -P  -W  -2 

SET  DLLLI NK=tl ink  /c  /n  /Tw  /L\borl andc\l i b  c0ds 

SET  DLLLI B=i mport  mathws  cws 

SET  DLLRC=rc  -r  -i \borl andc\i ncl ude 


Figure  19-2.  The  BCPDLL.BAT file  for  using  the  Borland  C++  3 ■  1  Compiler. 

You  should  run  either  the  MSCDLL.BAT  or  BCPDLL.BAT  batch  file  before  using  the  make 
files  shown  in  this  chapter. 

The  compiler  flags  are  stored  in  the  environment  variable  DLLCC.  You’ll  notice  an  ad¬ 
ditional  flag  beyond  those  defined  in  WINCC.  For  the  Microsoft  compiler,  this  flag  is  -ASw, 
and  for  the  Borland  compiler,  it’s  -ms!.  In  both  cases,  the  flag  tells  the  C  compiler  to  use  the 
small  memory  model  but  to  assume  that  the  data  segment  isn’t  the  same  as  the  stack  seg¬ 
ment.  (Note:  This  isn’t  normal,  yet  it’s  important  that  you  use  the  flag  for  compiling  a 
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dynamic  link  library  module.  The  implications  of  this  switch  are  discussed  in  greater  detail 
later  in  this  chapter.) 

The  initial  part  of  the  link  statement  is  defined  in  the  environment  variable  DLLLINK. 
When  using  the  Microsoft  compiler,  the  LIBENTRY.OBJ  object  module  must  be  included 
when  linking  the  DLL.  When  using  the  Borland  compiler,  the  CODS.OBJ  object  module  is 
substituted  for  COWS. OBJ.  In  both  cases,  these  object  modules  include  special  startup  code 
required  for  dynamic  link  libraries.  THE  DLLLIB  environment  variable  in  MSCDLL.BAT  in¬ 
dicates  a  different  run  time  library  for  DLLs. 

The  STRLIB  Library 

Figure  19-3  shows  the  four  files  necessary  to  create  the  STRLIB.DLL  dynamic  link  library 
module.  STRLIB  has  a  lot  in  common  with  the  Windows  programs  that  we’ve  been  writing, 
but  there  are  also  some  subtle  (and  some  not-so-subtle)  differences. 

STRLIB.MAK 

# - - 

#  STRLIB.MAK  make  file 

#  - 

strlib.dll  :  strlib.obj  strlib.def 

$(DLLLINK)  strlib,  strlib.dll,  NUL,  $(DLLLIB) .  strlib 
rc  -t  strlib.dll 

strlib.obj  :  strlib. c  strlib. h 
$ ( DLLCC )  strlib. c 


STRLIB.C 


/*  . . 

STRLIB.C  --  Library  module  for  STRPROG  program 
(c)  Charles  Petzold,  1992 

. - . - . */ 


#include  <windows.h> 

^include  "strlib.h" 

extern  "C"  { 

int  FAR  PASCAL  .export  WEP  (int)  ; 

} 


Figure  19-3.  The  STRLIB  library. 


(continued) 
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HANDLE  hStrings  [256]  ; 
short  nTotal  =  0  ; 

int  FAR  PASCAL  LibMain  (HANDLE  hlnstance,  WORD  wDataSeg,  WORD  wHeapSize, 

LPSTR  lpszCmdLine) 

{ 

if  (wHeapSize  >  0) 

UnlockData  (0)  ; 

return  1  ; 

} 

int  FAR  PASCAL  .export  WEP  (int  nParam) 

{ 

return  1  ; 

} 

BOOL  FAR  PASCAL  .export  AddString  (LPSTR  IpStringln) 

{ 

HANDLE  hString  ; 

NPSTR  npString  ; 

short  i,  nLength,  nCompare  ; 

if  (nTotal  ==  255) 
return  FALSE  ; 

if  (0  ==  (nLength  =  lstrlen  (IpStringln))) 
return  FALSE  ; 

if  (NULL  ==  (hString  =  Local A1 1 oc  ( LHND,  1  +  nLength))) 
return  FALSE  ; 

npString  =  Local  Lock  (hString)  ; 

Istrcpy  (npString,  IpStringln)  ; 

AnsiUpper  (npString)  ; 

LocalUnlock  (hString)  ; 

for  (i  =  nTotal  :  i  >0  ;  i -  - ) 

{ 

npString  =  LocalLock  (hStrings  [i  -  1])  ; 
nCompare  =  lstrcmpi  (IpStringln,  npString)  ; 

LocalUnlock  (hStrings  [i  -  1])  ; 

if  (nCompare  >  0) 

{ 

hStrings  [i]  =  hString  ; 
break  ; 

} 

hStrings  [i]  =  hStrings  [i  -  1]  ; 

} 


(continued) 
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if  (i  ==  0) 

hStrings  [0]  =  hString  ; 

nTotal-H-  ; 
return  TRUE  ; 

} 

BOOL  FAR  PASCAL  .export  DeleteString  (LPSTR  lpStringln) 

{ 

NPSTR  npString  ; 
short  i»  j,  nCompare  ; 

if  (0  ==  lstrlen  (lpStringln)) 
return  FALSE  ; 

for  ( i  =  0  ;  i  <  nTotal  ;  i++) 

f 

npString  =  Local  Lock  (hStrings  [ i ] )  ; 
nCompare  =  lstrcmpi  (npString,  lpStringln)  ; 

LocalUnlock  (hStrings  [i ] )  ; 

if  (nCompare  ==  0) 
break  ; 

} 

if  (i  ==  nTotal) 
return  FALSE  ; 

for  (j  =  i  ;  j  <  nTotal  ;  j++) 

hStrings  [j]  =  hStrings  [j  +  1]  ; 

nTotal--  ; 
return  TRUE  ; 

} 

short  FAR  PASCAL  .export  GetStrings  (FPSTRCB  1 pfnGetStrCal  1  Back,  LPVOID  IpParam) 

{ 

BOOL  bReturn  ; 

NPSTR  npString  ; 
short  i  ; 

for  (i  =  0  ;  i  <  nTotal  ;  i++) 

{ 

npString  =  LocalLock  (hStrings  [ i ] )  ; 

bReturn  =  1 pfnGetStrCal 1  Back  (npString,  IpParam)  ; 

LocalUnlock  (hStrings  [i ] )  ; 

if  (bReturn  ==  FALSE) 
return  i  +  1  ; 

} 

return  nTotal  ; 

} 
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STRLIB.H 

/* . 

STRLIB.H  header  file 
. - . - . */ 

typedef  BOOL  (FAR  PASCAL  .export  *  FPSTRCB)  (LPSTR,  LPVOID)  ; 
extern  "C"  { 

BOOL  FAR  PASCAL  .export  AddString  (LPSTR)  ; 

BOOL  FAR  PASCAL  .export  DeleteString  (LPSTR)  ; 

short  FAR  PASCAL  .export  GetStrings  (FPSTRCB.  LPVOID)  ; 

} 


STRLIB.DEF 


STRLIB.DEF  module  definition  file 


LIBRARY  STRLIB 

DESCRIPTION  'DLL  for  STRPROG  Program  (c)  Charles  Petzold.  1992' 

EXETYPE  WINDOWS 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  SINGLE 

HEAPSIZE  1024 

The  Library  Entry  Point 

The  most  obvious  difference  between  STRLIB. C  and  our  Windows  programs  is  the  ab¬ 
sence  of  WinMain.  In  its  place,  there  is  a  function  called  LibMain.  LibMain  is  called  from 
Microsoft’s  LIBENTRY.OBJ  or  Borland’s  CODS. OBJ  module.  This  is  required  because  of  the 
different  ways  in  which  Windows  programs  and  Windows  dynamic  link  libraries  are  ini¬ 
tialized  during  startup. 

For  a  program,  startup  code  is  created  that  contains  the  actual  entry  point.  On  entry 
into  a  program,  the  CPU  registers  contain  the  following  information: 


BX  Stack  size 

CX  Heap  size 

DI  Instance  handle 

SI  Previous  instance 

ES  Program  segment  prefix 
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The  start-up  code  (which  comes  from  Microsoft’s  SLIBCEW.LIB  or  Borland’s  COWS.OBJ) 
performs  some  initialization  and  then  calls  the  WinMain  function,  which  is  the  perceived 
entry  point  when  you  program  for  Windows  in  C. 

For  dynamic  link  libraries,  the  start-up  code  is  provided  in  LIBENTRY.OBJ  or  in 
CODS.OBJ.  Windows  calls  LibEntry  once  (when  the  first  program  that  requires  the 
dynamic  link  library  is  loaded)  with  the  CPU  registers  set  as  follows: 

DI  Instance  handle 

DS  Library’s  data  segment 

CX  Heap  size 

ES:SI  Command  line 


Note  the  differences  between  these  registers  and  those  for  a  Windows  program.  A  register 
containing  the  stack  size  isn’t  required,  because  library  modules  don’t  have  a  stack.  A 
register  containing  the  previous  instance  handle  isn’t  required,  because  library  modules 
can’t  have  multiple  instances.  For  most  uses  of  libraries,  the  command-line  parameter  in 
ES:SI  isn’t  used.  LibEntry  must  return  nonzero  if  initialization  is  successful  and  0  if  errors 
are  encountered.  A  failed  initialization  causes  Windows  to  not  run  the  program  that 
requires  the  library. 

LIBENTRY  initializes  the  local  heap  by  calling  Locallnit  and  then  calls  LibMain, 
which  is  in  STRLIB.C.  The  LibMain  definition  looks  like  this: 


int  FAR  PASCAL  LibMain  (HANDLE  hlnstance,  WORD  wDataSeg,  WORD  wHeapSize, 
LPSTR  IpszCmdLine) 

{ 

if  (wHeapSize  >  0) 

UnlockData  (0)  ; 


return  1  ; 
} 


This  simply  unlocks  the  data  segment  of  the  library  (which  is  locked  by  the  Locallnit  call 
in  LIBENTRY)  and  returns  1.  If  you  need  to  do  additional  initialization  when  the  library  is 
first  loaded,  you  can  do  it  here. 

Note  the  differences  implied  here  between  programs  and  libraries.  On  entry  to  a 
program,  the  start-up  code  passes  control  to  WinMain ,  which  performs  initialization  and 
then  enters  a  message  loop.  Multitasking  takes  place  during  GetMessage  calls.  The  program 
exits  the  message  loop  (and  WinMain)  only  when  the  program  retrieves  a  WM-QUIT  mes¬ 
sage  from  the  message  queue.  On  entry  to  a  library,  the  start-up  code  must  perform  initial¬ 
ization  and  then  return  control  to  Windows  with  a  nonzero  value.  The  rest  of  the  library 
sits  dormant  in  memory  until  another  module  calls  one  of  the  exported  functions. 
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Dynamic  Link  Library  Deinitialization 

A  dynamic  link  library  should  also  include  a  “deinitialization”  routine.  This  function  must 
be  called  WEP  (“Windows  Exit  Procedure”)  and  defined  as  follows: 

int  FAR  PASCAL  .export  WEP  (int  nParam) 

When  WEP  is  called  by  Windows,  nParam  can  be  equal  to  either  WEP_FREE_DLL  to  indi¬ 
cate  that  the  last  program  using  the  dynamic  link  library  is  terminating  and  the  DLL  is  no 
longer  needed  or  can  be  equal  to  WEP_SYSTEM_EXIT  to  indicate  that  Windows  is  shutting 
down.  In  either  case,  you  should  perform  deinitialization  and  return  1. 

STRLIB  doesn’t  need  to  perform  any  deinitialization,  so  it  simply  returns  1  from  WEP. 
Because  Windows  looks  for  a  function  specifically  named  WEP  in  the  dynamic  link 
library,  you  should  watch  out  for  C++  “name-mangling.”  When  compiling  for  C++,  define 
the  WEP  function  at  the  top  of  the  program  within  an  extern  statement: 

extern  "C"  { 

int  FAR  PASCAL  .export  WEP  (int  nParam)  ; 

} 

C++  name-mangling  is  something  we  haven’t  had  to  deal  with  yet,  so  here’s  a  brief 
explanation. 

C++  Name-Mangling  and  DLLs 

If  you’ve  used  EXEHDR  to  look  at  some  of  the  programs  in  previous  chapters,  most  of  them 
have  at  least  one  exported  function,  which  is  WndProc.  Other  exported  functions  include 
dialog  box  procedures,  window  procedures  for  program-defined  code,  call-back  func¬ 
tions,  and  window  subclassing  functions. 

If  you’re  compiling  in  C++  mode  (which  is  the  case  if  you  use  the  compilation  flags  in 
the  MSC.BAT  and  BCP.BAT  batch  files),  you’ll  notice  that  the  WndProc  function  shows  up 
in  the  EXEHDR  output  as: 

?WNDPROC@@ZCJGI I J@Z 

if  you’ve  used  the  Microsoft  compiler  and  as: 

@W  NDPROCSQUIUIUI L 

if  you’ve  used  the  Borland  compiler. 

These  are  examples  of  C++  “name-mangling.”  When  compiling  in  C++  mode,  the 
compiler  alters  function  names  with  codes  that  indicate  the  parameters  to  the  function  and 
the  return  value.  This  allows  C++  function  overloading  and  also  provides  some  error¬ 
checking  during  linking:  The  linker  won’t  resolve  a  function  call  in  one  module  with  the 
function  in  another  if  the  parameters  are  incorrect. 
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With  functions  exported  from  dynamic  link  libraries,  you’ll  probably  want  to  avoid  name- 
mangling.  As  you  can  see  from  the  preceding  example,  different  compilers  perform  name- 
mangling  in  different  ways.  If  functions  exported  from  a  DLL  are  name-mangled,  you 
would  only  be  able  to  use  the  DLL  from  a  program  compiled  with  the  same  compiler  as 
the  DLL! 

To  prevent  name-mangling,  you  define  exported  functions  as  shown  in  the  STRLIB.H 
header  file: 

extern  "C"  { 

BOOL  FAR  PASCAL  .export  AddString  ( LPSTR)  ; 

BOOL  FAR  PASCAL  .export  Del eteSt r i ng  (LPSTR)  ; 

short  FAR  PASCAL  .export  GetStrings  (FPSTRCB,  LPVOID)  ; 

1 

The  extern  statement  followed  by  "C"  instructs  the  compiler  not  to  mangle  the  function 
names  defined  within  the  bracket  range.  FPSTRCB  (“far  pointer  to  the  string  call-back”) — 
the  data  type  of  the  first  parameter  to  GetStrings — is  the  call-back  function  defined  in  a 
TYPEDEF  statement  in  STRLIB.H. 

The  STRLIB  Functions 

Aside  from  the  LibMain  initialization  function  and  WEP  exit  function,  STRLIB  contains 
only  the  three  functions  that  it  will  export  to  be  used  by  other  programs.  All  these  func¬ 
tions  are  defined  as  FAR  PASCAL  -export.  They  must  be  FAR  because  they  will  be  called 
from  the  code  segment  of  another  module  (STRPROG).  You  aren’t  required  to  define  them 
as  PASCAL,  however:  That’s  simply  a  convention  used  in  other  Windows  libraries  to  save  a 
few  bytes  of  space.  The  -export  keyword  is  necessary  to  make  the  functions  visible  out¬ 
side  the  program.  These  three  functions  use  Windows’  local  memory  allocation  functions 
to  allocate  space  in  the  local  heap  for  storing  the  character  strings.  Because  the 
AddString  function  allocates  moveable  local  blocks,  we’ve  essentially  given  Windows  the 
job  of  reorganizing  the  local  heap  when  necessary  to  allocate  more  memory. 

The  Library  Module  Definition  File 

The  module  definition  file  for  a  library  looks  somewhat  similar  to  the  .DEF  file  for  a  pro¬ 
gram,  but  there  are  also  significant  differences  between  the  two.  For  program  modules,  the 
module  definition  file  contains  a  NAME  statement  indicating  that  the  module  is  a  program. 
For  libraries,  the  first  line  is  a  LIBRARY  statement: 

LIBRARY  STRLIB 

This  statement  identifies  the  module  as  a  library.  The  library  CODE  statement  is  the  same 
as  that  used  for  programs: 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 
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You  can  also  use  LOADONCALL,  but  for  a  library  with  a  single  code  segment,  the  segment 
must  be  loaded  into  memory  so  that  the  initialization  routine  can  be  executed. 

For  a  Windows  program,  the  DATA  statement  indicates  that  the  data  segment  is 
MULTIPLE,  which  means  that  each  instance  of  the  program  uses  the  same  data  segment. 
For  the  STRLIB  library,  the  data  segment  is  marked  as  SINGLE,  because  a  library  can  have 
only  one  instance: 

DATA  PRELOAD  MOVEABLE  SINGLE 

If  the  library  doesn’t  include  a  data  segment,  the  DATA  statement  is: 

DATA  NONE 

Notice  how  these  directives  relate  to  the  information  obtained  from  EXEHDR. 

Because  we  want  STRLIB  to  use  its  local  heap  to  store  its  character  strings,  we  have  to 
give  it  a  local  heap  in  the  HEAPSIZE  statement: 

HEAPSIZE  1024 

This  is  the  initial  size  of  the  local  heap.  Windows  can  expand  the  data  segment  of  the 
library  to  accommodate  a  larger  heap  if  one  is  needed.  Notice  there’s  no  STACKSIZE 
statement  in  the  module  definition  file — a  library  module  doesn’t  have  its  own  stack. 

The  STRPROG  Program 

The  STRPROG  program,  shown  in  Figure  19-4,  is  fairly  straightforward.  The  two  menu  op¬ 
tions  (Enter  and  Delete)  invoke  dialog  boxes  that  allow  you  to  enter  a  string.  STRPROG 
then  calls  AddString  or  DeleteString.  When  the  program  needs  to  update  its  client  area, 
it  calls  GetStrings  and  uses  the  function  GetStrCallBack  to  list  the  enumerated  strings. 

STRPROG.MAK 

# . 

#  STRPROG.MAK  make  file 

#  . - . 


•  strprog.exe  :  strprog.obj  strprog.res  strprog.def 

$ ( WI N LI NK)  strprog,  strprog,  NUL,  $(WINLIB),  strprog 
rc  -t  strprog.res 

strprog.obj  :  strprog. c  strprog. h  strlib.h 
$(WINCC)  strprog. c 


strprog.res  : 
$ ( WI NRC ) 


strprog. rc  strprog. h 
strprog. rc 


Figure  19-4.  The  STRPROG  program. 
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STRPROG.C 

/* . - . 

STRPROG.C  --  Program  using  STRLIB  dynamic  link  library 
(c)  Charles  Petzold,  1992 

. - . - . --*/ 

♦include  <windows.h> 

♦include  <string.h> 

♦include  "strprog.h" 

♦include  "strlib.h" 

♦define  MAXLEN  32 

♦define  WM.DATACHANGE  WM.USER 

typedef  struct 
{ 

HDC  hdc  ; 
short  xText  ; 
short  yText  ; 
short  xStart  ; 
short  yStart  ; 
short  xlncr  ; 
short  ylncr  ; 
short  xMax  ; 
short  yMax  ; 

} 

CBPARM  ; 

long  FAR  PASCAL  .export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 

char  szAppName  []  =  "StrProg"  ; 
char  szString  [MAXLEN]  ; 

int  PASCAL  WinMain  (HANDLE  hlnstance,  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 

if  ( IhPrevInstance) 

{ 

wndclass. style  =  CS.HREDRAW  :  CS.VREDRAW  ; 

wndclass. lpfnWndProc  =  WndProc  ; 

wndclass. cbClsExtra  =  0  ; 

wndclass. cbWndExtra  =  0  ; 


(continued) 
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wndclass.hlnstance  =  hlnstance  ; 

wndclass.hlcon  =  Loadlcon  (NULL,  IDI_APPLICATION)  ; 

wndclass.hCursor  =  LoadCursor  (NULL,  I DC_ARR0W )  ; 

wndclass.hbrBackground  =  GetStockObject  (WHITE_BRUSH)  ; 
wndclass.lpszMenuName  =  szAppName  ; 
wndclass.lpszClassName  =  szAppName  ; 

RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "DLL  Demonstration  Program", 
WS.OVERLAPPEDWINDOW, 

CWJJSEDEFAULT,  CW_USEDEFAULT, 

CWJJSEDEFAULT,  CW_USEDE FAULT . 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

BOOL  FAR  PASCAL  .export  DlgProc  (HWND  hDlg,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

switch  (message) 

{ 

case  WM_I N ITDI ALOG  : 

SendDlgltemMessage  (hDlg,  IDD.STRING,  EM.LIMITTEXT, 
MAXLEN  -  1,  0L)  ; 

return  TRUE  ; 


case  WM.COMMAND  : 
switch  (wParam) 

{ 

case  I DOK  : 

GetDlgltemText  (hDlg,  IDD.STRING,  szString,  MAXLEN)  ; 
EndDialog  (hDlg,  TRUE)  ; 
return  TRUE  ; 

case  IDCANCEL  : 

EndDialog  (hDlg,  FALSE)  ; 
return  TRUE  ; 

} 

} 

return  FALSE  ; 

} 


(continued) 
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BOOL  FAR  PASCAL  .export  EnumCal 1  Back  (HWND  hwnd,  LONG  IParam) 

{ 

char  szClassName  [16]  ; 

GetClassName  (hwnd,  szClassName,  sizeof  szClassName)  ; 

if  (0  ==  strcmp  (szClassName,  szAppName)) 

SendMessage  (hwnd,  WM.DATACHANGE,  0,  0L)  ; 

return  TRUE  ; 

} 

BOOL  FAR  PASCAL  .export  GetStrCal 1  Back  (LPSTR  IpString,  CBPARM  FAR  *lpcbp) 

{ 

TextOut  ( 1 pcbp- >hdc .  lpcbp->xText,  lpcbp->yText, 

IpString,  Istrlen  (IpString))  ; 

if  ((lpcbp->yText  +=  lpcbp->ylncr)  >  lpcbp->yMax) 

{ 

lpcbp->yText  =  lpcbp->yStart  ; 
if  ((lpcbp->xText  +=  1 pcbp->xlncr)  >  lpcbp->xMax) 
return  FALSE  ; 

} 

return  TRUE  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  FARPROC  IpfnDlgProc,  IpfnEnumCal 1  Back  ; 
static  FPSTRCB  1 pfnGetStrCal 1  Back  ; 
static  HANDLE  hlnst  ; 

static  short  cxChar,  cyChar,  cxClient,  cyClient  ; 

CBPARM  cbparam  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

TEXTMETRIC  tm  ; 

switch  (message) 

{ 

case  WM.CREATE  : 

hlnst  =  ( ( LPCREATESTRUCT)  1 Param) ->hlnstance  ; 

IpfnDlgProc  =  MakeProcInstance  ((FARPROC)  DlgProc,  hlnst)  ; 

1 pfnGetStrCal 1  Back  =  (FPSTRCB) 

MakeProcInstance  ((FARPROC)  GetStrCallBack,  hlnst)  ; 
lpfnEnumCallBack  =  MakeProcInstance  ((FARPROC)  EnumCallBack, 

hlnst)  ; 

hdc  =  GetDC  (hwnd)  ; 

GetTextMetrics  (hdc,  &tm)  ; 


(continued) 
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cxChar  =  tm.tmAveCharWidth  ; 

cyChar  =  tm.tmHeight  +  tm.tmExternal Leading  ; 

ReleaseDC  (hwnd,  hdc)  ; 

return  0  ; 

case  WM_COMMAND  : 
switch  (wParam) 

{ 

case  IDM.ENTER  : 

if  (Dial ogBox  (hlnst,  "EnterDlg",  hwnd,  lpfnDlgProc)) 

{ 

if  (AddString  (szString)) 

EnumWindows  (1 pfnEnumCal 1  Back,  0L)  ; 

else 

MessageBeep  (0)  ; 

} 

break  ; 

case  I DM_DE LETE  : 

if  (Dial ogBox  (hlnst,  "DeleteDlg",  hwnd,  lpfnDlgProc)) 

{ 

if  ( Del eteSt ri ng  (szString)) 

EnumWindows  (1 pfnEnumCal 1  Back,  0L)  ; 

else 

MessageBeep  (0)  ; 

} 

break  ; 

} 

return  0  ; 
case  WM_SIZE  : 

cxClient  =  LOWORD  (IParam)  ; 
cyClient  =  HIWORD  (IParam)  ; 
return  0  ; 

case  WM.DATACHANGE  : 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 
return  0  ; 

case  WM_PA I  NT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

cbparam.hdc  =  hdc  ; 
cbparam.xText  =  cbparam.xStart  =  cxChar  ; 
cbparam.yText  =  cbparam.yStart  =  cyChar  ; 
cbparam.xlncr  =  cxChar  *  MAXLEN  ; 
cbparam.ylncr  =  cyChar  ; 

cbparam.xMax  =  cbparam.xlncr  *  (1  +  cxClient  /  cbparam.xlncr)  ; 
cbparam.yMax  =  cyChar  *  (cyClient  /  cyChar  -  1)  ; 

(continued) 
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GetStrings  ( 1 pf nGetStrCal 1  Back ,  &cbparam)  ; 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM.DESTROY  : 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 

} 


STRPROG.RC 

/* . 

STRPROG.RC  resource  script 
. */ 


#include  <windows.h> 
//include  "strprog.h" 


StrProg  MENU 

{ 

MENUITEM  "&Enter!",  IDM.ENTER 
MENUITEM  ^Delete!”,  I DM_DE LETE 
} 


EnterDlg  DIALOG  24,  24,  190,  44 
STYLE  WS.POPUP  !  WS_DLGFRAME 


{ 

LTEXT  "&Enter:", 

EDITTEXT 

DEFPUSHBUTTON  "Ok”, 
PUSHBUTTON  "Cancel". 

} 


0, 

IDD.STRING, 

IDOK, 

IDCANCEL, 


4,  8, 

32,  6. 

44,  24, 
114,  24, 


24,  8 
154,  12 
32,  14 
32,  14 


Del eteDl g  DIALOG  24,  24,  190,  44 
STYLE  WS_P0PUP  !  WS.DLGFRAME 


{ 

LTEXT 

EDITTEXT 

DEFPUSHBUTTON 

PUSHBUTTON 

} 


"&Delete:",  0, 

IDD.STRING, 
"Ok",  IDOK, 

"Cancel",  IDCANCEL, 


4,  8,  28.  8 

36,  6,  150,  12 

44,  24,  32,  14 

114,  24,  32,  14 
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STRPROG.H 

/* . . 

STRPROG.H  header  file 
. - . */ 

//define  IDM.ENTER  1 
//define  IDM.DELETE  2 
//define  IDD.STRING  0x10 


STRPROG.DEF 


STRPROG.DEF  module  definition  file 


NAME 

STRPROG 

DESCRIPTION 

'Program  using  STRLIB  DLL  (c)  Charles  Petzold,  1992' 

EXETYPE 

WINDOWS 

STUB 

'WINSTUB.EXE' 

CODE 

PRELOAD  MOVEABLE  DISCARDABLE 

DATA 

PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE 

1024 

STACKSIZE 

8192 

IMPORTS 

STRLIB. AddString 

STRLIB. DeleteString 

STRLIB. GetStrings 

STRPROG.C  includes  the  STRPROG.H  header  file,  which  simply  defines  the  con¬ 
stants  used  in  the  STRPROG.RC  resource  script.  It  also  includes  the  STRLIB.H  header  file; 
this  defines  the  three  functions  in  STRLIB  that  STRPROG  will  use.  The  extern  "C"  state¬ 
ment  in  STRLIB.H  prevents  these  function  names  from  being  mangled  when  compiling 
STRPROG.C. 

These  three  functions  are  also  listed  in  the  IMPORTS  section  of  STRPROG’s  module 
definition  file: 

IMPORTS  STRLIB. AddString 

STRLIB. Del eteSt r  i  ng 
STRLIB. GetStrings 

These  correspond  to  the  three  exported  functions  in  STRLIB.  The  IMPORTS  section 
directs  LINK  to  add  information  to  STRPROG.EXE  that  allows  Windows  to  dynamically 
link  STRPROG’s  calls  to  these  functions  with  the  actual  function  routines  in  STRLIB.DLL. 
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Running  STRPROG 

Once  you’ve  created  STRLIB.DLL  and  STRPROG.EXE,  you’re  ready  to  run  STRPROG. 
Before  you  do  so,  be  sure  that  STRLIB.DLL  is  in  the  current  directory  or  a  directory  that  is 
listed  in  the  PATH  string  of  the  MS-DOS  environment.  Windows  must  be  able  to  load 
STRLIB.DLL  when  you  execute  STRPROG.  If  Windows  can’t  find  STRLIB.DLL,  it  will 
display  a  message  box  telling  you  about  the  problem. 

When  you  execute  STRPROG.EXE,  Windows  performs  fixups  to  functions  in 
external  library  modules.  Many  of  these  functions  are  in  the  normal  KRNLx86,  USER,  and 
GDI  library  modules.  But  Windows  also  sees  that  the  program  calls  three  functions  from 
STRLIB,  so  Windows  loads  the  STRLIB.DLL  file  into  memory,  creates  reload  thunks  for  the 
three  functions,  and  calls  STRLIB’s  initialization  routine.  The  far  calls  within  STRPROG 
to  these  three  functions  are  dynamically  linked  with  the  reload  thunks  that  branch  to 
functions  in  STRLIB.  You  can  then  use  STRPROG  to  add  and  delete  strings  from  STRLIB’s 
internal  table.  STRPROG’s  client  area  shows  the  strings  currently  in  the  table. 

The  calls  from  STRPROG  to  the  AddString,  DeleteString ,  and  GetStrings  functions  in 
STRLIB  are  very  efficient  and  have  almost  no  overhead  except  for  the  reload  thunk.  In  fact, 
the  link  between  STRPROG  and  STRLIB  is  as  efficient  as  if  the  three  functions  in  STRLIB 
were  simply  in  another  moveable  code  segment  in  STRPROG.  So  what?  you  say.  Why 
do  I  have  to  make  this  a  dynamic  link  library?  Can’t  I  include  these  three  routines  in 
STRPROG.EXE? 

Well,  you  could.  In  one  sense,  STRLIB  is  nothing  more  than  an  extension  of 
STRPROG.  However,  you  may  be  interested  to  see  what  happens  when  you  execute  a  sec¬ 
ond  instance  of  STRPROG.  Because  only  one  instance  of  STRLIB  is  loaded  for  both  in¬ 
stances  of  the  program,  and  because  STRLIB  uses  its  own  local  heap  to  store  the  character 
strings,  all  instances  of  STRPROG  essentially  share  this  data.  (The  EnumCallBack  function 
in  STRPROG  serves  to  notify  all  STRPROG’s  instances  that  the  contents  of  STRLIB’s  data 
segments  have  changed.  EnumWindows  causes  Windows  to  call  EnumCallBack  with 
handles  to  all  parent  windows.  EnumCallBack  then  checks  to  see  if  the  class  name  of  each 
window  equals  “StrProg” — if  it  does,  the  function  sends  the  window  a  privately  defined 
WM_DATACHANGE  message.)  And  you  can  easily  imagine  an  enhanced  version  of 
STRLIB  managing  a  database  that  is  shared  by  several  instances  of  the  same  program  or  by 
single  instances  of  different  programs. 

Far  Function  Prologs 

In  Chapter  7,  among  other  things  involving  memory  management,  I  discussed  how  Win¬ 
dows  uses  the  prologs  of  far  pointers  to  correctly  set  a  data  segment  address  for  the  pro¬ 
gram.  When  Windows  loads  a  code  segment  into  memory,  it  alters  the  function  prolog  of 
all  exported  far  functions  in  the  segment.  The  table  on  the  following  page  shows  the  results 
of  that  process: 
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Nonexported 
Far  Function 

Exported  Function 
in  a  Program 

Exported  Function 
in  a  Library 

PUSH  DS 

NOP 

MOV  AX,  xxxx 

POP  AX 

NOP 

NOP 

NOP 

INC  BP 

INC  BP 

INC  BP 

PUSH  BP 

PUSH  BP 

PUSH  BP 

MOV  BP,  SP 

MOV  BP,  SP 

MOV  BP,  SP 

PUSH  DS 

PUSH  DS 

PUSH  DS 

MOV  DS,  AX 

MOV  DS,  AX 

MOV  DS,  AX 

These  three  prologs  differ  in  the  way  that  DS  (the  data  segment  address  register)  is  set  on 
entry  to  the  function.  In  each  case,  the  original  value  of  DS  is  saved  in  the  function  prolog 
and  restored  in  the  function  epilog. 

The  nonexported  far  function  simply  sets  AX  equal  to  DS  and  then  DS  equal  to  AX. 
This  does  nothing. 

For  an  exported  function  in  a  program,  Windows  inserts  NOPs  in  the  first  2  bytes  of 
the  function.  The  resultant  prolog  then  sets  DS  equal  to  AX.  This  prolog  requires  that  AX 
be  set  to  the  data  segment  of  the  particular  instance  of  the  program.  By  itself,  the  function 
is  incomplete.  You  must  call  MakeProcInstance  for  these  exported  functions  so  that  Win¬ 
dows  builds  an  “instance  thunk”  that  sets  AX  equal  to  the  data  segment  address  of  the  in¬ 
stance.  (The  only  case  in  which  you  don’t  need  to  call  MakeProcInstance  for  an  exported 
function  is  for  a  window  procedure  specified  in  a  window  class  structure.) 

The  exported  function  in  a  library  is  somewhat  simpler.  Because  the  library  can  have 
only  one  instance,  Windows  can  simply  insert  a  3-byte  instruction  that  sets  AX  equal  to  the 
data  segment  address  of  the  library.  Thus,  you  don’t  need  to  use  MakeProcInstance  with 
exported  far  functions  in  library  modules.  When  a  program  calls  a  far  function  exported 
from  a  library  module,  this  prolog  sets  the  data  segment  equal  to  the  library’s  data  seg¬ 
ment.  The  library  function  can  then  use  its  own  data  segment.  It  continues  to  use  the  stack 
segment  of  the  program  that  called  it. 

The  Use  of  Call-Back  Functions 

Now  that  we  know  what  these  function  prologs  look  like,  let’s  examine  what  happens 
when  STRPROG  calls  the  GetStrings  function.  GetStrings  requires  a  call-back  function  in 
STRPROG  called  GetStrCallBack. 

Because  GetStrCallBack  is  exported,  Windows  inserts  NOPs  in  the  first  2  bytes  of  the 
function  when  STRPROG’s  code  segment  is  loaded  into  memory.  While  processing  the 
WM_CREATE  message,  STRPROG  calls  MakeProcInstance  for  this  function: 
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1 pfnGetStrCal 1  Back  =  (FPSTRCB)  MakeProcInstance 
( ( FARPROC)  GetStrCal 1  Back,  hlnst)  ; 

On  return  from  MakeProcInstance ,  the  variable  IpfnGetStrCallBack  points  to  code 
that  looks  like  this: 

MOV  AX,  yyyy 
JMP  GetStrCal 1  Back 

where  yyyy  is  the  data  segment  address  of  this  instance  of  STRPROG. 

STRPROG  calls  GetStrings  to  update  its  client  area: 

GetStrings  (IpfnGetStrCallBack,  &cbparam)  ; 

The  GetStrings  function  is  in  STRLIB.  The  parameter  cbparam  is  a  structure  containing 
information  that  GetStrings  simply  passes  back  to  GetStrCallBack,  which  then  uses  the 
information  to  display  the  strings  in  the  client  area. 

In  STRLIB,  the  prolog  to  GetStrings  sets  AX  equal  to  the  data  segment  of  the  library, 
saves  the  current  value  of  DS  (the  data  segment  of  STRPROG),  and  sets  DS  equal  to  AX. 
Now  the  function  can  use  its  own  data  segment  to  obtain  the  strings  currently  stored.  When 
it  obtains  a  string,  it  calls  the  call-back  function  passed  as  a  parameter  to  GetStrings-. 

bReturn  =  IpfnGetStrCallBack  (npString,  IpParam)  ; 

This  actually  calls  the  instance  thunk  for  GetStrCallBack  set  up  by  MakeProcInstance.  The 
instance  thunk  sets  AX  equal  to  STRPROG’s  data  segment.  The  function  prolog  saves  the 
current  value  of  DS  (the  data  segment  of  STRLIB)  and  sets  DS  equal  to  AX.  Now 
GetStrCallBack  is  using  STRPROG’s  own  data  segment  and  can  process  the  string.  When 
GetStrCallBack  returns  control  to  GetStrings ,  the  function  epilog  restores  the  original 
value  of  DS,  which  is  STRLIB’s  data  segment.  GetStrings  is  ready  to  find  the  next  string. 

When  GetStrings  is  finished,  the  function  epilog  restores  the  value  of  DS  to 
STRPROG’s  data  segment.  As  you  can  see,  although  control  bounces  back  and  forth  be¬ 
tween  STRPROG  and  STRLIB,  each  module  is  always  using  its  own  data  segment.  During 
this  entire  process,  however,  the  stack  segment  never  changes.  It  is  always  STRPROG’s 
stack  segment.  For  code  in  STRPROG,  this  situation  is  just  fine.  For  code  in  STRLIB,  it  can 
pose  some  problems. 

THE  DS  !=  SS  ISSUE 

The  segmented  architecture  of  the  Intel  8086  family  of  microprocessors  has  been  giving 
programmers  grief  for  many  years  now.  But  nowhere  does  segmented  architecture  cause 
more  problems  than  in  Windows  libraries.  If  you  skipped  the  first  half  of  Chapter  7,  think¬ 
ing  that  you’d  never  need  to  know  about  segmented  architecture  and  the  intricacies  of  near 
and  far  pointers,  now  is  the  time  to  read  it.  And  even  if  you’ve  read  it  carefully,  you  might 
still  benefit  from  this  quick  review. 
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The  Intel  8086  family  of  microprocessors  operating  in  real  mode  can  address  1  MB  of 
memory.  This  memory  is  addressed  by  a  combination  of  a  16-bit  segment  address  and  a  16- 
bit  offset  address.  The  16-bit  segment  address  marks  the  beginning  of  a  64-KB  area  of 
memory.  The  offset  address  is  relative  to  the  beginning  of  the  segment.  In  protected  mode, 
the  segment  address  references  a  24-bit  base  address  in  a  descriptor  table.  The  offset  ad¬ 
dress  is  added  to  this. 

The  8086-family  microprocessors  have  four  registers  that  contain  segment  addresses: 
the  code  segment  register  (CS),  the  data  segment  register  (DS),  the  stack  segment  register 
(SS),  and  the  extra  segment  register  (ES).  The  instruction  pointer  (IP)  always  addresses 
code  within  the  code  segment.  The  stack  pointer  (SP)  always  addresses  the  stack  within 
the  stack  segment.  Registers  that  address  data  can  do  so  relative  to  any  of  the  four  current 
segments.  When  programming  in  C,  16-bit  pointers  that  specify  only  an  offset  address  are 
called  near  or  short  pointers,  and  32-bit  pointers  that  contain  both  a  segment  address  and 
an  offset  address  are  called  far  or  long  pointers. 

In  C,  all  variables  defined  outside  functions  (on  the  external  level)  and  all  variables 
defined  as  static  within  functions  are  stored  in  static  memory.  The  compiler  uses  near 
pointers  relative  to  the  8086  data  segment  (DS)  to  address  variables  stored  in  static 
memory. 

All  parameters  to  functions  and  all  variables  within  functions  that  are  not  defined  as 
static  are  stored  on  the  stack.  The  compiler  uses  near  pointers  relative  to  the  8086  stack 
segment  (SS)  to  address  the  stack. 

When  you  use  a  near  pointer  in  a  C  program,  the  pointer  can  reference  a  variable  ei¬ 
ther  in  static  memory  or  on  the  stack.  The  compiler  has  no  way  to  determine  whether  the 
near  pointer  is  an  offset  to  DS  or  SS.  For  this  reason,  C  programs  are  normally  constructed 
to  use  the  same  segment  for  data  and  the  stack.  Simply  put,  DS  ==  SS.  This  is  almost  re¬ 
quired  for  a  C  implementation  on  8086-family  microprocessors,  because  C  does  not  differ¬ 
entiate  between  pointers  to  static  variables  and  pointers  to  stack  variables. 

Let’s  take  an  example.  In  a  small-model  or  medium-model  program,  you  can  use  the 
normal  C  strlen  function  to  find  the  length  of  a  string.  The  parameter  to  strlen  is  a  near 
pointer  to  the  string: 

i Length  =  strlen  (pString)  ; 

The  string  itself  could  be  stored  either  in  static  memory  or  on  the  stack.  You  could  define 
pString  like  this: 

char  *pString  =  "This  is  a  string"  ; 

In  this  case,  the  string  “This  is  a  string”  is  stored  in  static  memory,  and  the  near  pointer  is 
relative  to  the  beginning  of  the  data  segment.  However,  you  could  do  something  like  this 
within  a  function: 
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char  szString  [20]  ; 

[other program  lines] 
i Length  =  strlen  (szString)  ; 

In  this  case,  the  szString  array  takes  up  20  bytes  on  the  stack.  When  you  refer  to  szString , 
you’re  actually  referring  to  a  near  pointer  relative  to  the  stack  segment. 

How  does  the  strlen  function  know  whether  the  near  pointer  is  an  offset  in  the  stack 
segment  or  in  the  data  segment?  It  doesn’t.  If  you  take  a  look  at  the  assembly-language  code 
for  strlen ,  you’ll  find  something  like  this: 

_strl en  NEAR  PROC 

PUSH  BP  ; 

MOV  BP,  SP 

MOV  OX,  DI  ; 

MOV  AX,  DS  ; 

POP  ES,  AX 

MOV  DI , [BP+4]  ; 

XOR  AX.  AX 

MOV  CX,  -1 

REPNZ  SCASB  ; 

NOT  CX  ; 

DEC  CX 

XCHG  AX,  CX 

MOV  DI,  DX  ; 

MOV  SP.  BP  ; 

POP  BP 

RET 

_strlen  ENDP 

The  strlen  function  assumes  that  the  near  pointer  is  an  offset  in  the  data  segment. 
It  sets  ES  equal  to  DS  using  this  code: 

MOV  AX,  DS 
MOV  ES,  AX 

It  then  uses  ES  to  scan  the  string  for  a  terminating  0.  To  write  a  strlen  function  that  would 
work  with  a  near  pointer  in  the  stack  segment,  you  would  need  to  replace  these  lines  with: 

MOV  AX,  SS 
MOV  ES,  AX 

But  you’ve  never  had  to  worry  about  this  little  problem  in  Windows  programs,  because  DS 
equals  SS. 

Windows  dynamic  libraries  are  another  story.  The  data  segment  is  the  library’s  own 
data  segment,  but  the  stack  segment  is  the  stack  of  the  caller.  That  is,  DS  !=  SS.  If  you  call 
strlen  in  a  Windows  library  for  a  string  that  is  stored  on  the  stack,  the  function  won’t  work 


Prologue 
Save  DI 

Set  ES  equal  to  DS 

Get  DI  ptr  off  stack 

Search  for  zero  in  ES : DI 
Calculate  length 

Restore  DI 
Epilogue 
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correctly,  because  the  strlen  function  assumes  that  the  near  pointer  is  relative  to  the  data 
segment.  When  you  first  realize  the  implications  of  this,  you’re  likely  to  assume  that  pro¬ 
gramming  Windows  dynamic  libraries  is  very  difficult.  Let’s  just  say  that  it’s  not  quite  as 
carefree  a  process  as  writing  a  Windows  program,  but  the  job  certainly  isn’t  impossible. 
After  all,  the  bulk  of  Windows  consists  of  dynamic  libraries — the  KRNLx86,  USER,  and 
GDI  modules. 

At  one  time,  the  recommended  practice  was  to  use  no  normal  C  library  functions 
within  a  dynamic  library  and  to  instead  write  your  own  functions.  This  restriction  has  now 
been  loosened,  and  information  is  available  to  let  you  use  C  library  functions  intelligently. 
The  conventions  followed  in  the  strlen  function  hold  in  most  of  the  functions  in  the  normal 
C  run  time  library  distributed  with  the  Microsoft  and  Borland  C  compilers:  Most  functions 
that  accept  pointers  assume  that  the  pointer  is  relative  to  the  data  segment  and  do  not 
assume  that  DS  is  equal  to  SS. 

When  you  compile  C  source  code  for  a  small-model  Windows  library,  include  the 
switch  -ASw  for  the  Microsoft  compiler  and  -ms!  for  the  Borland  compiler.  These  switches 
tell  the  compiler  to  assume  that  DS  is  not  equal  to  SS.  Nothing  very  magical  happens  here. 
The  primary  purpose  of  these  switches  is  to  alert  you  to  possible  problems  in  your  code. 
For  instance,  within  a  function,  you  might  define  an  array  and  a  pointer: 

int  array  [3]  ; 
int  *ptr  ; 

If  you  say: 

array  [0]  =  array  [1]  +  array  [2]  ; 

the  compiler  uses  SS  to  reference  the  elements  of  array ,  because  the  compiler  knows  that 
array  is  on  the  stack.  However,  you  might  have  code  like  this: 

ptr  =  array  ; 

*ptr  =  *(ptr  +  1)  +  *(ptr  +  2)  ; 

In  the  first  statement,  the  compiler  assigns  the  near  address  of  array  (which  happens  to  be 
referenced  from  the  stack  segment)  to  the  near  pointer  ptr  But  when  generating  code  for 
the  second  line,  the  compiler  assumes  that  ptr  references  a  variable  in  the  data  segment. 
That’s  wrong. 

If  you  have  a  program  with  a  construction  like  this  and  you  compile  with  the  -ASw 
switch  and  a  warning  level  of  1  or  2,  you’ll  get  a  warning  message  for  the  assignment  of  the 
array  address  to  ptr. 

warning  C4058:  address  of  automatic  (local)  variable  taken,  DS  !=  SS 
for  the  Microsoft  compiler  and: 

Cannot  convert  'int  _ss  *'  to  'int  *'  in  function  [function  name] 
for  the  Borland  compiler. 
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You  can  translate  these  messages  as:  “You’ve  assigned  the  address  of  a  local  variable 
on  the  stack  to  a  near  pointer.  Future  use  of  this  near  pointer  will  involve  the  data  segment. 
You’ve  specified  that  you  want  the  compiler  to  assume  DS  is  not  equal  to  SS.  This  assign¬ 
ment  statement  contradicts  your  intentions.” 

You  can  fix  this  by  making  ptr  a  far  pointer,  as  follows: 

int  array  [3]  ; 
int  far  *ptr  ; 

ptr  =  array  ; 

Now  the  compiler  assigns  the  full  32-bit  address  of  array  (the  stack  segment  and  the  offset) 
to  ptr  You’re  safe  in  using  ptr  Or  you  can  make  array  a  static  variable: 

static  int  array  [3]  ; 
int  *ptr  ; 

ptr  =  array  ; 

The  compiler  now  assumes  that  ptr  references  data  in  the  data  segment;  this  is  correct, 
because  array  is  defined  as  static. 

Don’t  assume  that  you’ll  always  be  alerted  to  problems  like  this.  Here’s  another 
example.  You  have  a  function  that  sums  up  the  first  100  elements  of  an  integer  array: 

int  sumup  (int  array  []) 

{ 

int  i ,  n  =  0  ; 

for  ( i  =  0  ;  i  <  100  ;  i++) 
n  +=  array  [i]  ; 
return  n  ; 

1 

If  you  call  this  function  and  the  array  happens  to  be  on  the  stack,  you’re  in  trouble: 

int  array  [100]  ; 

[other program  lines] 

sumup  (array)  ;  /*  A  problem  here  */ 

This  won’t  even  generate  a  warning  message,  but  it’s  obviously  incorrect.  How  do  you  get 
around  it?  Use  far  pointers.  Define  the  function  like  this: 

int  sumup  (int  far  array  []) 

and  call  the  function  like  this: 

sumup  ((int  far  *)  array)  ; 

Or  make  array  a  static  variable: 

static  int  array  [100]  ; 

[other program  lines] 

sumup  (array)  ;  /*  No  problem  here  */ 


933 


SECTION  V:  DATA  EXCHANGE  AND  LINKS 


This  is  a  better  solution  for  an  array  of  this  size  anyway,  because  it  avoids  putting  200  bytes 
on  the  calling  program’s  stack. 

You  can  avoid  many  of  the  DS  !=  SS  problems  simply  by  not  using  stack  variables  and 
instead  defining  all  your  local  variables  as  static.  If  you  want  to  use  stack  variables  for  some 
items  to  save  space  in  the  data  segment,  you  should  avoid  using  the  stack  either  for  arrays 
or  for  any  variables  that  require  pointers.  Finally,  if  you  use  pointers  with  stack  variables, 
make  them  far  pointers. 

The  parameters  to  a  library  function  are  always  on  the  stack.  If  you  need  to  use  a 
pointer  to  reference  a  function  parameter,  use  a  far  pointer. 


OTHER  LIBRARY  RESTRICTIONS 

The  start-up  code  that  is  added  to  a  Windows  program  during  linking  with  LINK  uses  the 
registers  passed  to  the  program  on  entry,  together  with  some  DOS  function  calls,  to  set 
various  global  variables  in  the  program’s  data  segment.  These  variables  allow  programs  ac¬ 
cess  to  the  DOS  environment  and  to  other  information.  This  start-up  code  isn’t  present  in 
Windows  libraries.  For  this  reason,  you  can’t  use  the  getenv  or  putenv  functions  in  librar¬ 
ies,  nor  can  you  use  global  variables  that  refer  to  this  information. 

I  mentioned  earlier  that  a  dynamic  library  module  doesn’t  receive  messages.  How¬ 
ever,  a  library  module  can  call  GetMessage  and  PeekMessage.  The  messages  the  library 
pulls  from  the  queue  with  these  functions  are  actually  messages  for  the  program  that  called 
the  library  function.  In  general,  the  library  works  on  behalf  of  the  program  calling  it,  a  rule 
that  holds  for  most  Windows  functions  that  a  library  calls.  The  obvious  exceptions  are  local 
memory  allocation  functions.  As  you  saw  with  the  STRLIB  library,  these  functions  use  the 
library’s  local  heap. 

A  library  can  allocate  global  memory  for  the  program  instance  calling  the  library. 
The  global  memory  blocks  are  automatically  freed  when  the  program  instance  terminates. 

A  dynamic  library  can  load  resources  (such  as  icons,  strings,  and  bitmaps)  either  from 
the  library  file  or  from  the  file  of  the  program  that  calls  the  library.  The  functions  that  load 
resources  require  an  instance  handle.  If  the  library  uses  its  own  instance  handle  (which 
is  passed  to  the  library  during  initialization),  then  the  library  can  obtain  resources  from 
its  own  file.  To  load  resources  from  the  calling  program’s  .EXE  file,  the  library  function 
requires  the  instance  handle  of  the  program  calling  the  function. 

Registering  window  classes  and  creating  windows  in  a  library  can  be  a  little  tricky. 
Both  the  window  class  structure  and  the  CreateWindow  call  require  an  instance  handle. 
Although  you  can  use  the  library  module’s  instance  handle  in  creating  the  window  class 
and  the  window,  the  window  messages  still  go  through  the  message  queue  of  the  program 
calling  the  library  when  the  library  creates  the  window.  If  you  must  create  window  classes 
and  windows  within  a  library,  then  it’s  probably  best  to  use  the  calling  program’s 
instance  handle. 


934 


Chapter  19:  Dynamic  Link  Libraries 


Because  messages  for  modal  dialog  boxes  are  retrieved  outside  a  program’s  message 
loop,  you  can  create  a  modal  dialog  box  in  a  library  by  calling  DialogBox.  The  instance 
handle  can  be  that  of  the  library,  and  the  hwndParent  parameter  to  DialogBox  can  be  set 
to  NULL. 

DIFFERENT  METHODS  FOR  SPECIFYING  LINKS 

STRPROG  and  STRLIB  show  only  one  of  several  possible  methods  for  exporting  from  one 
module  and  importing  into  another.  In  STRLIB. C,  all  exported  functions  have  the  -export 
keyword. 

STRPROG. DEF’s  IMPORTS  section  refers  to  both  the  library  module  and  the  function 
names: 

IMPORTS  STRLIB. AddString 

STRLIB. DeleteString 
STRLIB. GetStrings 

Here’s  another  method:  The  module  definition  file  for  STRLIB. DEF  can  include  an 
EXPORTS  section  that  can  assign  “ordinals”  to  each  of  the  functions.  These  are  simply 
unique  positive  integers  preceded  by  @: 

EXPORTS  AddString  @1 
DeleteString  @2 
GetStrings  @3 

STRPROG. DEF’s  IMPORTS  section  then  references  these  numbers: 

IMPORTS  AddString  =  STRLIB. 1 
DeleteString  =  STRLIB. 2 
GetStrings  =  STRLIB. 3 

This  method  may  yield  a  smaller  .EXE  file,  because  the  file  simply  stores  the  ordinal 
numbers  rather  than  the  names  of  all  the  functions.  For  a  large  number  of  imported  func¬ 
tions,  this  method  provides  a  significant  reduction  in  .EXE  size.  It’s  a  little  trickier  to  use 
than  the  first  method,  because  you  have  to  be  sure  you  get  the  numbers  right. 

You  can  also  use  function  names  in  the  program  that  are  different  from  those  in  the 
library.  For  instance,  suppose  that  in  STRPROG  you  use  the  names  AddStr,  DelStr ;  and 
GetStr  instead  of  AddString ,  DeleteString ,  and  GetStrings.  You  can  reference  these  aliases 
to  the  real  function  names  in  the  IMPORTS  section: 

IMPORTS  AddStr  =  STRLIB. AddString 

DelStr  =  STRLIB. DeleteString 
GetStr  =  STRLIB. GetStrings 

Or  if  the  module  definition  file  for  STRLIB  defines  ordinals  for  each  of  the  exported  func¬ 
tions,  the  IMPORTS  section  will  look  like  this: 
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IMPORTS  AddStr  =  STRLIB.l 
Del Str  =  STRLIB.2 
GetStr  =  STRLIB.3 

Even  if  you  don’t  explicitly  specify  ordinal  numbers  for  the  exported  functions  in  the 
library  module  definition  file,  LINK  assigns  ordinal  numbers  to  the  functions.  You  can 
determine  these  ordinal  numbers  by  running  EXEHDR  on  the  library  module. 


USING  IMPORT  LIBRARIES 

I  implied  earlier  that  in  writing  your  own  library  module,  you’re  adding  an  extension  to 
Windows — an  extension  that  serves  you  in  a  manner  similar  to  that  of  the  standard 
KRNLx86,  USER,  and  GDI  library  modules.  So,  you  ask,  why  do  I  have  to  list  all  the  names 
of  imported  functions  from  my  own  dynamic  libraries  when  I  don’t  have  to  specifically  im¬ 
port  the  KRNLx86,  USER,  and  GDI  functions  that  I  use?  Well,  in  the  early  days  of  Windows 
programming  (long  before  the  introduction  of  the  product),  programmers  had  to  do  pre¬ 
cisely  that.  They  ended  up  with  module  definition  files  that  looked  like  this: 

IMPORTS  USER . Reg i sterCl ass 
USER.CreateWindow 

[etc.,  etc.,  etc.] 

This  process  was  simplified  greatly  by  the  use  of  “import  libraries.”  Import  libraries  are 
much  like  object  libraries  in  that  the  linker  uses  them  to  resolve  function  calls  within  a 
program.  But  the  import  library  contains  no  (or  very  little)  code,  only  a  reference  that  rec¬ 
onciles  the  function  name  you  use  in  your  program  with  the  library  module  containing  this 
function  and  the  actual  function  name.  This  is  exactly  what  you  do  in  the  IMPORTS  section 
of  a  .DEF  file.  An  import  library  for  STRLIB  would  allow  the  linker  to  know  that  a  function 
call  to  AddString  is  really  an  imported  function  from  STRLIB  called  AddString  or  an 
imported  function  from  STRLIB  with  an  ordinal  number  of  1. 

When  you  link  a  Windows  program  or  dynamic  link  library,  the  LIBW.LIB  or  IM- 
PORT.LIB  import  library  reconciles  all  the  normal  Windows  functions  you  use  in  the  pro¬ 
gram  (mostly  from  KRNLx86,  USER,  and  GDI)  and  the  ordinal  numbers.  That’s  why  this 
import  library  must  be  specified  in  the  library  field  of  the  link  command  line.  Think  of  it 
this  way:  The  linker  has  to  resolve  all  calls  that  a  program  makes  to  external  functions.  It 
can  do  this  in  one  of  three  ways:  extract  the  function  itself  from  an  object  library,  get  a  ref¬ 
erence  to  a  library  module  name  and  function  name  (or  ordinal)  from  an  import  library,  or 
get  a  library  module  name  and  function  name  (or  ordinal)  from  the  IMPORTS  section  of 
the  module  definition  file. 

You  can  create  an  import  library  for  a  dynamic  library  module  by  running  the 
IMPLIB  program  included  with  the  Microsoft  and  Borland  C  compilers.  The  syntax  is: 

IMPLIB  1 i bname. LIB  libname.DEF 
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IMPLIB  looks  only  at  the  EXPORTS  section  of  the  module  definition  file.  It  creates  a  file 
with  the  extension  .LIB.  After  the  import  library  is  created,  you  can  add  normal  object 
modules  to  the  .LIB  file  using  the  LIB. EXE  program  included  with  the  Microsoft  C/C++ 
Compiler  or  the  TLIB.EXE  program  included  with  Borland  C. 

Figure  19-5  shows  a  revised  make  file  and  module  definition  file  for  STRLIB;  Figure 
19-6  on  the  following  page  shows  a  revised  make  file  and  module  definition  file  for 
STRPROG.  The  new  STRLIB  make  file  creates  an  import  library  called  STRLIB. LIB.  In  the 
STRPROG  make  file,  this  import  library  must  be  specified  in  the  library  field  of  the  LINK 
command  line.  The  new  STRPROG. DEF  file  requires  no  IMPORTS  section. 

STRLIB2.MAK 

# 

#  STRLIB2.MAK  make  file 

#  . 

strlib.dll  :  strlib. obj  strlib.def 

KDLLLINK)  strlib,  strlib.dll,  NUL,  $  ( DLLLI B ) ,  strlib 

rc  -t  strlib.dll 

implib  strlib. lib  strlib.def 

strlib. obj  :  strlib. c  strlib. h 
$ ( DLLCC )  strlib. c 


STRLIB2.DEF 


STRLIB2.DEF  module  definition  file 


LIBRARY  STRLIB 


DESCRIPTION 

EXETYPE 

CODE 

DATA 

HEAPSIZE 


’DLL  for  STRPROG  Program  (c)  Charles  Petzold,  1992' 
WINDOWS 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  SINGLE 
1024 


EXPORTS  AddString  @1 

DeleteString  @2 
GetStrings  @3 


Figure  19-5.  A  revised  make  file  and  module  definition  file  for  the  STRLIB  library. 
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STRPROG2.MAK 

# . . 

#  STRPR0G2.MAK  make  file 

#  . - . . 


strprog.exe  :  strprog.obj  strprog.res  strprog.def 

$(WINLINK)  strprog,  strprog.  NUL,  $( WINLIB) ,  strlib.  strprog 
rc  -t  strprog.res 

strprog.obj  :  strprog. c  strprog. h  strlib. h 
$ ( W I NCC )  strprog. c 

strprog.res  :  strprog. rc  strprog. h 
$(WINRC)  strprog. rc 


STRPROG2.DEF 


STRPR0G2.DEF  module  definition  file 


NAME  STRPROG 


DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 


'Program  using  STRLIB  DLL  (c)  Charles  Petzold,  1992' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  MULTIPLE 
1024 
8192 


Figure  19-6.  A  revised  make  file  and  module  definition  file  for  the  STRPROG  program. 


DYNAMIC  LINKING  WITHOUT  IMPORTS 

Rather  than  have  Windows  perform  dynamic  linking  when  your  program  is  first  loaded 
into  memory,  you  can  link  a  program  with  a  library  module  while  the  program  is  running. 
We  used  this  technique  in  Chapter  15  when  we  had  to  call  the  DeviceMode  function  in  a 
printer  driver  module. 

For  instance,  you  would  normally  call  the  Rectangle  function  like  this: 

Rectangle  (hdc,  xLeft,  yTop,  xRight,  yBottom)  ; 

You  can  also  call  Rectangle  in  a  very  roundabout  manner.  You  first  use  typedefto  define  a 
function  type  for  Rectangle : 
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typedef  BOOL  (FAR  PASCAL  * FPRECT )  (HDC,  int,  int,  int,  int)  ; 

You  then  define  two  variables: 

HANDLE  hLibrary  ; 

FPRECT  lpfnRectangle  ; 

Now  you  set  hLibrary  to  the  handle  of  the  library  and  lpfnRectangle  to  the  address  of  the 
Rectangle  function: 

hLibrary  =  LoadLibrary  ("GDI . EXE") 

lpfnRectangle  =  (FPRECT)  GetProcAddress  (hLibrary,  MAKEINTRESOURCE  (27)) 

The  LoadLibrary  function  returns  an  MS-DOS  error  code  (less  than  32)  if  the  library  file 
can’t  be  found.  In  GetProcAddress ,  the  second  parameter  is  a  number  (27)  that  you  convert 
to  a  far  pointer  to  a  string  by  setting  the  segment  address  equal  to  0;  27  is  the  ordinal 
number  of  Rectangle  obtained  from  the  EXEHDR  listing  of  GDI. EXE.  Now  you  can  call 
the  function  and  then  free  the  library: 

lpfnRectangle  (hdc,  xLeft,  yTop,  xRight,  yBottom)  ; 

FreeLibrary  (hLibrary)  ; 

For  libraries  in  which  the  module  definition  file  doesn’t  define  ordinals  for  the 
exported  functions,  you  can  use  the  function  name  in  the  GetProcAddress  call: 

lpfnFunction  =  GetProcAddress  (hLibrary,  "Functi onName")  ; 

Don’t  use  this  method  for  linking  to  modules  that  use  ordinal  numbers  for  the  exported 
functions.  The  names  of  the  functions  in  a  library  remain  resident  in  memory  only  if  the 
module  definition  file  doesn’t  include  ordinals  or  if  the  keyword  RESIDENTNAME  is  used 
with  the  functions  in  the  EXPORTS  statement. 

Although  this  technique  doesn’t  make  much  sense  for  the  Rectangle  function,  it  will 
definitely  come  in  handy.  You  need  to  use  it  when  you  don’t  know  the  name  of  the  library 
module  until  run  time,  as  is  the  case  with  the  DeviceMode  function  in  the  printer  drivers. 

The  code  above  uses  the  LoadLibrary  and  FreeLibrary  functions.  Windows  main¬ 
tains  “reference  counts”  for  all  library  modules.  LoadLibrary  causes  the  reference  count  to 
be  incremented.  The  reference  count  is  also  incremented  when  Windows  loads  any  pro¬ 
gram  that  uses  the  library.  FreeLibrary  causes  the  reference  count  to  be  decremented,  as 
does  the  termination  of  an  instance  of  a  program  that  uses  this  library.  When  the  reference 
count  is  0,  Windows  can  discard  the  library  from  memory,  because  the  library  is  no  longer 
needed. 


RESOURCE-ONLY  LIBRARIES 

Any  function  in  a  dynamic  link  library  that  Windows  programs  or  other  libraries  can  use 
must  be  exported.  However,  a  dynamic  link  library  need  not  contain  any  exported  func¬ 
tions.  What  would  such  a  DLL  contain?  The  answer  is  resources. 
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Let’s  say  you’re  working  on  a  Windows  application  that  requires  a  number  of  bitmaps. 
Normally  you  would  list  these  in  the  resource  script  of  the  program  and  load  them  into 
memory  with  the  LoadBitmap  function.  But  perhaps  you  want  to  create  several  sets  of  bit¬ 
maps,  each  set  customized  for  one  of  the  major  display  adapters  used  with  Windows.  It 
would  make  most  sense  to  store  these  different  sets  of  bitmaps  in  different  files,  because  a 
user  would  need  only  one  set  of  bitmaps  on  the  fixed  disk.  These  files  are  resource-only 
libraries. 

Figure  19-7  shows  how  to  create  a  resource-only  library  file  called  BITLIB.DLL  that 
contains  nine  bitmaps.  The  BITLIB.RC  file  lists  all  the  separate  bitmap  files  and  assigns 
each  one  a  number.  To  create  BITLIB.DLL,  you  need  nine  bitmaps  named  BITMAP1.BMP, 
BITMAP2.BMP,  and  so  forth.  You  can  create  these  bitmaps  in  the  Windows  PAINTBRUSH 
program. 

BITLIB.MAK 

# . 

#  BITLIB.MAK  make  file 

#  . 

bitlib.dll  :  bitlib.obj  bitlib.def  bitlib.res 

$(DLLLINK)  bitlib.  bitlib.dll,  NUL,  $(DLLLIB) ,  bitlib 
rc  -t  bitlib.res  bitlib.dll 

bitlib.obj  :  bitlib.c 
$ ( DLLCC )  bitlib.c 

bitlib.res  :  bitlib. rc 
$ ( DLLRC )  bitlib. rc 


BITLIB.C 


/* . - . . . . . 

BITLIB.C  --  Code  entry  point  for  BITLIB  dynamic  link  library 
(c)  Charles  Petzold,  1992 


*/ 


#include  <windows.h> 
extern  "C"  { 

int  FAR  PASCAL  .export  WEP  (int  nParam)  ; 

} 

int  FAR  PASCAL  LibMain  (HANDLE  hlnstance,  WORD  wDataSeg, 
WORD  wHeapSize,  LPSTR  IpszCmdLine) 


Figure  19-7.  The  BITLIB  library. 


(continued) 
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{ 

if  (wHeapSize  >  0) 

UnlockData  (0)  ; 

return  1  ; 

} 

int  FAR  PASCAL  .export  WEP  (int  nParam) 

{ 

return  1  ; 

} 


BITLIB.RC 

/* . 

BITLIB.RC  resource  script 


1  BITMAP  bitmapl.bmp 

2  BITMAP  bitmap2.bmp 

3  BITMAP  bitmap3.bmp 

4  BITMAP  bitmap4.bmp 

5  BITMAP  bitmap5.bmp 

6  BITMAP  bitmap6.bmp 

7  BITMAP  bitmap7.bmp 

8  BITMAP  bitmap8.bmp 

9  BITMAP  bitmap9.bmp 


BITLIB.DEF 


BITLIB.DEF  module  definition  file 


LIBRARY  BITLIB 


DESCRIPTION 

EXETYPE 

CODE 

DATA 


'Bitmap  DLL  for  SHOWBIT.EXE' 
WINDOWS 

PRELOAD  MOVEABLE  DISCARDABLE 
PRELOAD  MOVEABLE  SINGLE 


The  SHOWBIT  program,  shown  in  Figure  19-8  beginning  on  the  following  page, 
reads  the  bitmap  resources  from  BITLIB  and  copies  them  to  the  clipboard.  You  can  cycle 
through  the  bitmaps  by  pressing  a  key  on  the  keyboard. 
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SHOWBIT.MAK 

# . 

#  SHOWBIT.MAK  make  file 

#  . . 

showbit.exe  :  showbit.obj  showbit.def 

$(WINLINK)  showbit,  showbit,  NUL,  $(WINLIB),  showbit 
rc  -t  showbit.exe 

showbit.obj  :  showbit. c 
$ ( W I NCC )  showbit. c 


SHOWBIT.C 


/* 


SHOWBIT.C  --  Shows  bitmaps  in  BITLIB  dynamic  link  library 
(c)  Charles  Petzold,  1992 


*/ 


^include  <windows.h> 


long  FAR  PASCAL  ^export  WndProc  (HWND,  UINT,  UINT,  LONG)  ; 


int  PASCAL  WinMain  (HANDLE  hlnstance.  HANDLE  hPrevInstance, 
LPSTR  IpszCmdLine,  int  nCmdShow) 

{ 

static  char  szAppName  []  =  "ShowBit"  ; 

HWND  hwnd  ; 

MSG  msg  ; 

WNDCLASS  wndclass  ; 


if  ( IhPrevInstance) 

{ 

wndclass. style 
wndclass. lpfnWndProc 
wndclass. cbClsExtra 
wndclass. cbWndExtra 
wndclass. hlnstance 
wndclass. hlcon 
wndclass. hCursor 
wndclass.hbrBackground 
wndclass. IpszMenuName 
wndclass. 1 pszCl assName 


=  CS.HREDRAW  !  CS_VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hlnstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL,  IDC.ARR0W)  ; 
=  GetStockObject  (WHITE.BRUSH)  ; 
=  NULL  ; 

=  szAppName  ; 


Figure  19-8.  The  SHOWBIT  program. 


(continued) 
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RegisterClass  (&wndclass)  ; 

} 

hwnd  =  CreateWindow  (szAppName,  "Show  Bitmaps  from  BITLIB  (Press  Key)", 
WS.OVERLAPPEDWINDOW, 

CWJJSEDEFAULT,  CW.USEDEFAULT, 

CWJJSEDEFAULT,  CW.USEDEFAULT, 

NULL,  NULL,  hlnstance,  NULL)  ; 

ShowWindow  (hwnd,  nCmdShow)  ; 

UpdateWindow  (hwnd)  ; 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 

void  DrawBitmap  (HDC  hdc,  short  xStart,  short  yStart,  HBITMAP  hBitmap) 

{ 

BITMAP  bm  ; 

HDC  hMemDC  ; 

POINT  pt  ; 

hMemDC  =  CreateCompatibleDC  (hdc)  ; 

SelectObject  (hMemDC,  hBitmap)  ; 

GetObject  (hBitmap,  sizeof  (BITMAP),  (LPSTR)  &bm)  ; 
pt.x  =  bm.bmWidth  ; 
pt.y  =  bm.bmHeight  ; 

BitBlt  (hdc.  xStart,  yStart,  pt.x,  pt.y,  hMemDC,  0,  0,  SRCCOPY)  ; 

DeleteDC  (hMemDC)  ; 

} 

long  FAR  PASCAL  .export  WndProc  (HWND  hwnd,  UINT  message,  UINT  wParam, 

LONG  IParam) 

{ 

static  HANDLE  hLibrary  ; 
static  short  nCurrent  =  1  ; 

HANDLE  hBitmap  ; 

HDC  hdc  ; 

PAINTSTRUCT  ps  ; 

switch  (message) 

{ 


(continued) 
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case  WM_CREATE  : 

if  ((hLibrary  =  LoadLibrary  ("BITLIB.DLL"))  <  32) 
DestroyWindow  (hwnd)  ; 

return  0  ; 

case  WM.CHAR  : 

if  (hLibrary  >=  32) 

{ 

nCurrent  ++  ; 

Inval idateRect  (hwnd,  NULL,  TRUE)  ; 

) 

return  0  ; 
case  WM_PAINT  : 

hdc  =  BeginPaint  (hwnd,  &ps)  ; 

if  (hLibrary  >=  32) 

{ 

if  (NULL  ==  (hBitmap  =  LoadBitmap  (hLibrary, 

MAKEINTRESOURCE  (nCurrent)))) 

{ 

nCurrent  =  1  ; 

hBitmap  =  LoadBitmap  (hLibrary, 

MAKEINTRESOURCE  (nCurrent))  ; 

} 

if  (hBitmap) 

{ 

DrawBitmap  (hdc,  0,  0,  hBitmap)  ; 

DeleteObject  (hBitmap)  ; 

} 

) 

EndPaint  (hwnd,  &ps)  ; 
return  0  ; 

case  WM_DESTROY  : 

if  (hLibrary  >=  32) 

FreeLibrary  (hLibrary)  ; 

PostQuitMessage  (0)  ; 
return  0  ; 

} 

return  DefWindowProc  (hwnd,  message,  wParam,  IParam)  ; 
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SHOWBIT.DEF 


SHOWBIT. DEF  module  definition  file 


NAME  SHOWBIT 


DESCRIPTION  Program  to  show  bitmaps  from  BITLIB  (c)  Charles  Petzold,  1992' 
EXETYPE  WINDOWS 

STUB  *  W I NSTUB . EXE  * 

CODE  PRELOAD  MOVEABLE  DISCARDABLE 

DATA  PRELOAD  MOVEABLE  MULTIPLE 

HEAPSIZE  1024 

STACKSIZE  8192 


During  processing  of  the  WM_CREATE  message,  SHOWBIT  gets  a  handle  to  BITLIB.DLL: 

if  ( (hLibrary  =  LoadLibrary  ( "BITLIB . DLL") )  <  32) 

DestroyWindow  (hwnd) 

If  BITLIB.DLL  isn’t  in  the  current  directory  or  in  a  directory  accessible  through  the  PATH 
string  in  the  MS-DOS  environment,  Windows  displays  a  message  box  noting  the  problem. 
When  the  user  presses  OK,  LoadLibrary  returns  an  MS-DOS  error  code  (less  than  32),  in 
which  case  SHOWBIT  terminates. 

SHOWBIT  can  obtain  a  handle  to  a  bitmap  by  calling  LoadBitmap  with  the  library 
handle  and  the  number  of  the  bitmap: 

hBitmap  =  LoadBitmap  (hLibrary,  MAKEINTRESOURCE  (nCurrent))  ; 

This  returns  an  error  if  the  bitmap  corresponding  to  the  number  nCurrent  isn’t  valid  or  if 
not  enough  memory  exists  to  load  the  bitmap. 

While  processing  the  WM-DESTROY  message,  SHOWBIT  frees  the  library: 

FreeLibrary  (hLibrary)  ; 

When  the  last  instance  of  SHOWBIT  terminates,  the  reference  count  of  BITLIB.DLL  drops 
to  0  and  the  memory  it  occupies  is  freed.  As  you  can  see,  this  is  a  simple  method  of 
implementing  a  “clip  art”  program  that  could  load  precreated  bitmaps  (or  metafiles)  into 
the  clipboard  for  use  by  other  programs. 
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Special  Characters 

&  (underlining),  343,  434 
//  (comments  symbol),  32 
386  enhanced  mode,  273 
8080,  8088,  8086,  80286,  80386,  and  80486 
microprocessors.  See 
microprocessors 

8514/A  video  adapter,  313-14,  512,  514 

A 

ABORTDOC  subfunction  of  Escape ,  748 
abort  procedures  in  printing 
banding  and,  781-86 
implementing,  759-63 
printing  dialog  boxes  and,  763-68 
setting,  757-58 

ABOUT1  example  program,  408-21 
ABOUT2  example  program,  421-35 
ABOUT3  example  program,  435-43 
About  dialog  box,  408-43 
accelerators.  See  keyboard  accelerators 
ACCELERATORS  statement,  391 
active  window,  92.  See  also  input  focus 
AddAtom  function,  830 
addresses,  memory,  274-75 
aliases,  function  name,  935-36 
alignment.  See  also  text  output,  alignment 
brushes,  580-82 
one-line  text,  715-16 
Alt  key 

generating  ANSI  characters,  133 
keystroke  messages,  95 
system  keystrokes  and,  91,  93-94,  884 
ampersand  (&),  343,  434 
animation  example  program,  641-45 


anisotropic  mapping  mode,  528-29, 
533-34 

ANSI  character  set,  129-30 
AnsiLowerBuff  function,  131 
AnsiLower  function,  131 
AnsiNext  function,  132 
AnsiPrev  function,  132 
AnsiToOemBuff  function,  133 
AnsiToOem  function,  129, 132-33 
AnsiUpperBuff  function,  131 
AnsiUpper  function,  131 
ANSI_VAR_FONT  identifier,  664 
AppendMenu  function,  355-57,  367,  384, 
387-88 

Apple  Computer,  Inc.,  5 
Apple  LaserWriter  Plus  device,  510,  511 
application  modal  windows,  181 
application  programs 
C/C++  and  {see  C/C++) 
calls  to,  from  Windows,  41-42 
compiling  {see  compiling;  make  files; 

module  definition  files) 
data  {see  data) 

data  exchange  {see  clipboard;  dynamic 
data  exchange  (DDE)) 
entry  points,  24,  28-29 
files  {see  files) 

functions  {see  functions;  libraries) 
graphics  {see  graphics;  Graphics  Device 
Interface  (GDI)) 
handles  {see  handles) 

Hungarian  notation,  27-28 
as  icons,  198 

identifiers  {see  identifiers) 
initialization  of  MDI,  901-2 
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application  programs,  continued 
input  (see  child  window  controls; 

keyboard;  mouse;  timer) 
links  (see  dynamic  link  libraries  (DLLs); 

Multiple  Document  Interface  (MDI)) 
memory  (see  memory) 
messages  (see  messages) 

MS-DOS,  in  Windows,  10,  11 
name  for  DDE  server,  824-25 
output  (see  display  devices;  printer 
devices;  printing;  text  output) 
output  models,  15-16 
programmers  (see  programmer 
concepts) 

resources  (see  resources) 
text  (see  characters;  fonts;  text) 
users  (see  user  concepts) 
variables  (see  variables) 
window  procedures  (see  window 
procedures) 
windows  (see  windows) 

Arc  function,  542,  544,  562-68 
arcs,  563-68 

ARCS  example  program,  563-68 
ArrangelconicWindows  function,  886 
arrow  mouse  cursor,  136 
ASCII  character  sets,  127,  128-29 
aspect  ratios,  512-13 
atoms,  DDE,  830-31 
ATOM  statement,  830 
AUTOEXEC.BAT  file,  19 

B 

background  colors.  See  also  brushes 
filling  in  line  gaps  and,  549-50 
icons  as,  246 

setting,  for  child  window  controls,  31, 
243-45 
text,  55 

transparent  mode,  118 


banding  technique 

abort  procedure  and,  781-86 
implementing,  778-81 
overview,  777-78 

batch  files,  setting  environment  variables 
with,  19,  912 

BCC.EXE  compiler,  22-23 

BCP. BAT  file,  19 

BCPDLL.BAT  file,  912 

BEEPER1  example  program,  182-86 

BEEPER2  example  program,  188-93 

beep  function,  182 

BeginPaint  function,  24,  38,  51-52,  496 
binary  raster  operation  (ROP2)  codes.  See 
also  raster  operation  (ROP)  codes 
color  and,  556-57 
drawing  modes,  550-52 
example  program  with,  552-56 
identifiers,  551 

bit-block  transfers.  See  also  pattern  block 
transfers 

color  conversions,  638-39 
coordinates,  628-29 
drawing  bitmaps  on  display,  631-32 
example  program  swapping  rectangle 
contents,  635-38 

example  program  with  animation,  641-4!; 
mapping  mode  conversions,  639-40 
memory  device  contexts  and,  634-38 
printer  capability  for,  747 
ROP  codes  and,  629-30,  632-34 
BitBlt  function.  See  bit-block  transfers 
bit-flag  identifiers,  30.  See  also  identifiers 
BITLIB  example  library,  940-41 
BITMAPCOREHEADER  data  structure,  609 
BITMAP  data  structure,  575-76,  579,  620-2: 
BITMAPFILEHEADER  data  structure, 

608-9 

bitmap  fonts,  668-69,  673 
BITMAPINFO  data  structure,  619 
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BITMAPINFOHEADER  data  structure,  608 
bitmaps 

bit-block  transfers  ( see  bit-block 
transfers) 

clipboard  transfers,  797-804 
color  and,  606-7 
color  format,  622-23 
creating,  384 

creating,  as  objects,  619-21 
creating,  with  text,  385-86 
data  structures,  575-76,  579,  608-9, 
620-22 

device-dependent,  GDI  object  format, 
619-23 

device-independent  ( see  device¬ 
independent  bitmaps  (DIB)  format) 
dimensions,  623 

example  program  creating  brushes 
with,  320-24 

example  program  using,  in  menus,  374-89 
Image  Editor  and,  313-15 
memory  device  contexts,  384-85,  623-25 
metafiles  vs.,  605-6  (see  also  metafiles) 
monochrome  format,  621-22 
pattern  block  transfers,  625-29 
in  resource-only  DLLs,  940-45 
scaling,  386-87 

stretching,  173,  628-29,  640-41 
transfer  coordinates,  628-29 
uses  for,  319-20 

BITMAP  statement,  324,  577,  621-22 
BLOWUP1  example  program,  167-74 
BLOWUP2  example  program,  797-804 
Bit.  See  bit-block  transfers;  pattern  block 
transfers 

BM  (button  message)  identifiers,  215-16 

BMP  extension.  See  bitmaps 

BN  (button  notification)  identifiers,  215 

boldface  characters,  693 

Borland  C++  3.1, 19.  See  also  compiling 

Borland  Programmer’s  Platform,  20 


Borland  Turbo  C++,  20 
BOUNCE  example  program,  641-45 
bounding  boxes  and  filled  areas,  559-63 
brushes.  See  also  pens 
alignment,  580-82 

background  color  and  stock,  31  (see  also 
background  colors) 
bitmaps  and,  320-24,  575-79 
child  window  controls  and,  224-25 
data  structure,  574,  579 
dithering  and,  572 
example  program  creating,  with 
bitmaps,  320-24 

filling  areas  with,  558-59,  572-74 
handles,  26 
hatch  styles,  573 
as  objects,  186,  224 
origins,  225 

pattern  block  transfers  and,  625 
style  identifiers,  574 
BS  (brush  style)  identifiers,  574 
BS  (button  style)  identifiers,  212-18 
BTNLOOK  example  program,  209-20 
BURGERMASTER  segment,  278 
button  controls 

button  text,  218-19 
Cancel  button,  431-32 
check  boxes,  217-18 
child  window  messages  to  parent 
windows,  214-15 
colors  for,  222-23 
creating  child  windows,  213-14 
data  structure,  213,  232 
example  program,  209-20 
group  boxes,  218 
input  focus  and,  219-20 
message  identifiers,  215-16 
notification  identifiers,  215 
OK  button,  431-32 
owner-draw,  213,  225-33 
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button  controls,  continued 

parent  window  messages  to  child 
windows,  215-16 
push  buttons,  216-17 
radio  buttons,  218 
style  identifiers,  212-18 
visible  and  enabled,  219 

c 

C/C++ 

case  conversion  function,  131 
compiling  options,  19-24 
control  characters,  325 
file  deletion,  649,  656 
file  input/output  functions,  463 
memory  allocation  functions, 
281-82,  303 

name-mangling  and  DLLs,  918-19 
standard  file  functions,  463 
string  functions,  466 
text  output  functions,  59-60,  444 
time  functions,  204 
versions  required  for  sample 
programs,  19-20 

calculator  example  program,  454-61 
call-back  functions 

in  dynamic  link  libraries,  928-29 
functions  requiring,  187 
processing  timer  messages,  186-93 
proper  handling  of,  191-93 
calloc  function,  281-82,  303 
Cancel  buttons,  431-32 
caption  bars,  33 
CAPTION  statement,  418 
carets.  See  also  mouse  cursors 
cursors  vs.,  118 
example  program,  119-27 
functions,  118-19 
cascading  windows,  885 
case  conversion,  131 
CF  (choose  font)  identifiers,  786 


CF  (clipboard  format)  identifiers,  792-93, 
813-14 

CGA.  See  Color  Graphics  Adapter 
CbangeClipboardChain  function,  817 
ChangeMenu  function,  367 
character  messages 

dead-character,  92,  111-12 
example  program  displaying 
information  about,  112-18 
example  text  editor  program,  119-27 
keystroke  messages  vs.,  92  ( see  also 
keystroke  messages) 
processing,  111 
as  queued  messages,  42 
translating  keystroke  messages  into,  35, 
108-11 
characters 

C-style  control,  325 
dead,  92,  111-12 

fonts  and  characteristics  of,  692-96 
( see  also  fonts) 
graying  strings  of,  664-66 
inserting  strings  of,  into  list  boxes, 
254-55 

messages  (see  character  messages) 
sets  of  (see  character  sets) 
size,  57,  664 
space  between,  663 
strings  of,  as  DDE  atoms,  830-31 
strings  of,  as  resources  (see  character 
string  resources) 
character  sets 
ANSI,  129-30 

ASCII  and  extended  ASCII,  127 
fonts  and,  130,  694  (see  also  fonts) 
functions  for  converting,  131-32 
international,  131-33 
MS-DOS  and,  132-33 
numeric  keypad  and  extended,  133 
OEM  and  extended  ASCII,  128-29 
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character  string  resources 
creating  and  using,  325 
example  program  displaying  error 
messages,  326 
memory  and,  326-28 
uses  for,  324-25 
charts,  pie,  569-71 
check  boxes,  217-18 
CHECKBOX  statement,  420 
CheckDlgButton  function,  430 
CHECKER1  example  program,  150-54 
CHECKER2  example  program,  155-60 
CHECKER3  example  program,  161-67 
CheckMenuItem  function,  354,  368 
CheckRadioButton  function,  430 
child  window  controls 

button  class  (see  button  controls) 
color  identifiers,  223 
colors,  220-33 
control  IDs,  46l 

in  dialog  boxes,  419-21,  427-30  (see 
also  dialog  boxes) 
edit  class  (see  edit  controls) 
list  box  class  (see  list  box  controls) 

OK  and  Cancel  buttons  as,  431-32 
overview,  207-8 

scroll  bar  class  (see  scroll  bar  controls) 
static  class,  233-34 
user-defined,  435-43 
child  window  procedures 

DDE  server  program,  848-49 
for  MDI  document  windows,  904-6 
power  of  MDI,  906 
child  windows 

controls  (see  child  window  controls) 
creating,  for  MDI  documents,  902-3 
creating,  with  button  controls,  213-24 
creating  multiple,  165-66 
data  structure,  214 
example  program  with,  l6l— 67 
hit-testing  with,  160-61 


child  windows,  continued 

messages  from  parent  windows  to, 
215-16 

messages  to  parent  windows,  214-15 
overview,  13 

static  styles,  233-34  (see  also  window 
style  (WS)  identifiers) 
visible  and  enabled,  219 
window  procedures  (see  child  window 
procedures) 

ChooseColor function,  488-90 
CHOOSEFONT  data  structure,  724-27 
ChooseFont  function,  680,  724-27 
choose  font  (CF)  identifiers,  786 
Chord  function,  562-68 
chords,  563-68 
classes.  See  window  classes 
CLASS  statement,  418 
class  style  (CS)  identifiers,  25,  30,  145, 
516-17 

CL.EXE  compiler,  21-22 
client  area 

background  color,  31 
calculating  size  of,  67-68 
coordinates,  146,  520,  582 
invalidating  and  repainting,  37-39 
mouse  messages,  136-45 
overview,  47 

paint  information  structure,  26,  38, 
51-54,  496 

painting  text  on  (see  text  output) 
writing  outside  of,  173-74 
CLIENTCREATESTRUCT  data  structure, 
885-86,  902 
client  programs,  DDE 

examples,  854-66,  873-81 
servers  and,  823-24 
ClientToScreen  function,  146,  520,  582 
client  windows,  MDI,  885 
clipboard 

CLIPBOARD  program  vs.,  791 
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clipboard,  continued 

delayed  rendering,  811-12 
edit  controls  and,  252 
example  program  transferring  bitmaps, 
797-804 

example  program  transferring  bitmaps 
from  DLL  to,  940-45 
format  identifiers,  792-93,  813-14 
memory  usage,  795-96 
opening  and  closing,  796 
private  data  formats,  813-15 
standard  data  formats,  792-93 
transferring  bitmaps,  797-804 
transferring  metafiles,  804-9 
transferring  multiple  data  items,  809-11 
transferring  text,  793-95 
viewer  programs  (see  clipboard 
viewers) 

CLIPBOARD  program  (CLIPBRD.EXE), 
791,  813 

clipboard  viewers 
chain  of,  815-16 
CLIPBOARD  program,  791,  813 
example  program  with  simple,  818-22 
functions  and  messages,  816-18 
CLIP  (clipping)  identifiers,  695 
clipping  rectangles  and  regions,  53,  55, 
586-92 

CLIPVIEW  example  program,  818-22 
clock  example  program,  199-206 
CLOCK  program,  178-79 
clock  ticks,  177 
CloseClipboard  function,  794 
CloseMetaFile  function,  498,  646 
CLOVER  example  program,  587-92 
code  pages,  129 
code  segments 
attributes,  287-89 
discardable,  279 
fixed  and  moveable,  278-79 
global  memory  layout,  279-81 


code  segments,  continued 
libraries,  919-20 

memory  models  and,  282-83,  285-86 
movement  problems,  286-87 
multiple,  283-85 
options,  40,  919-20 
CODE  statement,  40,  287-88,  919-20 
cold  links,  825-27,  849-50 
Color  Graphics  Adapter  (CGA),  313-14,  512 
COLOR  (system  color)  identifiers,  221-22, 
233 
colors 

background  (see  background  colors) 
bit-block  transfers  and  conversions  of, 

638-39 

bitmap  format,  622-23 
bitmaps  and,  606-7 
brushes  and,  572-74 
of  button  controls,  222-23 
check  boxes,  217 

child  window  controls  and,  220-33 
data  structures,  608-9 
display  device  information,  513-14 
dithered,  186,  552,  572 
macros  for  getting,  185-86,  542 
messages  from  child  windows  to  parent 
windows,  223-25 
multiple  instances  and,  246 
pens  and,  549-50,  556-57 
scroll  bar  controls,  245 
selecting  and  viewing,  with  common 
dialog  box  library  function,  488-90 
selecting  and  viewing,  with  dialog  box, 
235-46 

selecting  and  viewing,  with  scroll  bars, 
235-46 

system,  221-22,  233 
text,  55 

Windows’  use  of,  185-86,  542,  608-9 
COLORS1  example  program,  235-46 
COLORS2  example  program,  448-53 
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COLORS3  example  program,  488-90 
CombineRgn  function,  585-86,  591 
comments  symbol  (//),  32 
common  dialog  box  library 
color  selection  with,  488-90 
make  files  and,  23 
overview,  462 

communications,  interprocess.  See 

clipboard;  dynamic  data  exchange 
(DDE);  dynamic  link  libraries  (DLLs) 
compact  memory  model,  282-83,  285-86 
compiling 

dynamic  link  libraries,  912-13 
make  files  {see  make  files) 
memory  models  and,  283-85 
module  definition  files  {see  module 
definition  files) 
resources,  23-24,  306-9 
switches,  19-24, 191,  932 
CONNECT  example  program,  138-42 
consistency  issues,  6-7,  355 
constant  identifiers,  ^identifiers 
context  code,  keystroke,  95 
contexts.  See  device  contexts 
context  switching  vs.  multitasking,  7 
control  characters,  C-style,  325 
control  color  (CTLCOLOR)  identifiers,  223 
controls.  See  child  window  controls 
CONTROL  statement,  420-21,  435-43 
conversations,  DDE.  See  also  dynamic  data 
exchange  (DDE) 
client  initiation,  847-48,  864-65 
client  termination,  854 
cold  link,  825-27,  849-50 
hot  link,  827-28,  851-54 
server  termination,  866 
warm  link,  828-30 
coordinates 

bit-block  transfers,  628-29 
client-area,  137,  520 


coordinates,  continued 

conversion  between  device  and  logical, 
520-22 

conversion  between  screen  and  client- 
area,  146-47 

conversion  macro,  143,  543 
data  structures  for,  34,  142-43 
device  vs.  logical,  517,  518  (see  also 
device  coordinates;  logical 
coordinates) 
dialog  box  template,  413 
extraction  macro,  137,  543 
filled  areas,  559-63 
logical  vs.  device,  517,  519  {see  also 
device  coordinates;  logical 
coordinates) 

mapping  modes  and  {see  mapping 
modes) 

screen,  519-20 
virtual  vs.  device,  494 
whole-window,  520 
CopyMetaFile  function,  655-56 
CopyRect  function,  584 
CountClipboardFormats  function,  811 
COWM  file,  283 
COWS  file,  23 

C  Programming  Language,  The 
(Kernighan  and  Ritchie),  15 
CPU  registers,  916-17 
CreateBitmap  function,  384,  386,  575, 
619-20 

CreateBitmapIndirect  function,  384,  387, 
575,  579,  619-22 

CreateBrushlndirect  function,  574 
CreateCaret  function,  118-19 
CreateCompatibleBitmap  function,  384, 
575,  619-20,  623,  624 
CreateCompatibleDC  function,  384,  385, 
497,  624 

CreateDC  function,  173,  497,  734-37 
CreateDialog  function,  445-46,  460 
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CreateDI Bitmap  function,  609,  618-19 
CreateDIBPatternBrush  function,  609 
CreateDiscardableBitmap ,  619-20 
CreateEllipticRgn  function,  585 
CreateEllipticRgnlndirect  function,  585 
CreateFont  function,  680-81 
CreateFontlndirect  function,  385, 

680-81,  692 

CreateHatch Brush  function,  224,  573-74 
CreateIC  function,  204,  385,  497,  508 
CreateMenu  function,  355-57,  387 
CreateMetaFile  function,  498,  646-48 
CreatePatternBrush  function,  224,  574 
CreatePen  function,  545-49 
CreatePenlndirect  function,  545-49 
CreatePolygonRgn  function,  585 
CreatePolyPolygonRgn  function,  585 
CreateRectRgn  function,  584,  591 
CreateRectRgnlndirect  function,  584 
CreateRoundRectRgn  function,  585 
CreateSolidBrush  function,  186,  224, 
243-45,  573 

CREATESTRUCT  data  structure,  214 
CreateWindow  function 

child  windows,  165-66,  208,  213-14 

dialog  boxes  and,  460 

DLLs  and,  934 

menus  and,  345 

overview,  24,  32-33 

scrolling  and,  70 

create  window  (CW)  identifiers,  25,  33 
cross-hair  mouse  cursor,  136 
CS  (class  style)  identifiers,  25,  30, 145, 
516-17 

CTEXT  statement,  413-14,  434 
CTLCOLOR  (control  color)  identifiers,  223 
Ctrl  key 

character  messages,  110-11 
system  keyboard  accelerators  in 
MDI,  884 

cursor  (IDC)  identifiers,  25,  31,  136 


cursor  movement  keys  and  scrolling, 
100-108 

cursors.  See  carets;  mouse  cursors 
CURSOR  statement,  318 
CW  (create  window)  identifiers,  25,  33 
CWS.LIB  file,  283,  909 

D 

data 

clipboard,  delayed  rendering  of,  811-12 
exchange  (see  clipboard;  dynamic  data 
exchange  (DDE)) 
files  (see  files) 

links  (see  Multiple  Document  Interface 
(MDI)) 

structures  (see  data  structures) 
types,  25-26, 143, 188,  290 
Data  Interchange  Format  (DIF),  792-93 
data  segments 

attributes,  287-89 

dynamic  link  libraries,  920,  930-34 

local  memory,  281-82 

locking,  301-2 

memory  models  and,  282-83,  285-86 
movement  problems,  286-87 
options,  40,  920 

DATA  statement,  40,  287-88,  920 
data  structures 

bitmap,  575-76,  579,  608-9,  620-22 
child  window,  214 
choose  font,  724-27 
DDE,  830 

logical  brush,  574,  579 
logical  font,  385,  692-96 
logical  pen,  547 

MDI  client  window,  885-86,  902 

MDI  document  window,  886-87,  902-3 

menu  item  template,  357 

message,  26,  34-35 

metafile  picture,  805-9 

open  file  name,  486 
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data  structures,  continued 
overview,  26 

owner-draw  button,  213,  232 
paint,  26,  38,  51-34,  496 
point,  34, 142-43 
rectangle,  26,  38, 143 
RGB  color,  608-9 
text  metrics,  57-58,  698-700 
variable  names,  27 
window  class,  26,  29-32 
data  types,  25-26, 143, 188,  290.  See  also 
handle  types 

date 

getting  time  and,  204 
international  support  and,  205-6 
DDE.  See  DDE  Management  Library 

(DDEML);  dynamic  data  exchange 
(DDE) 

DdeAccessData  function,  866 
DdeClientTransaction  function,  880-81 
DdeCmpStringHandles  function,  867 
DdeConnect  function,  879-80 
DdeCreateDataHandle  function,  866,  880 
DdeCreateStringHandle  function,  867,  879 
DdeDeinitialize  function,  881 
DdeDisconnect  function,  881 
DdeFreeDataHandle  function,  866 
DdeFreeStringHandle  function,  867,  879 
DdeGetData  function,  866 
DDE.H  header  file,  825,  847 
Ddelnitialize  function,  866,  879 
DdeKeepStringHandle  function,  867 
DDE  Management  Library  (DDEML) 
classic  DDE  vs.,  866-67  ( see  also 
dynamic  data  exchange  (DDE)) 
example  server  and  client  programs, 
867-81 

DdeNameService  function,  879 
DDEPOP1  example  program,  831-54 
DDEPOP2  example  program,  867-72, 
879-81 


DdePostAdvise  function,  880 
DdeQueryString  function,  867,  879 
DdeUninitialize  function,  866 
dead-character  messages,  92,  111-12 
default  window  processor.  See 
DefWindowProc  function 
DEF  extension,  39 
DefFrameProc  function,  886 
DefMDIChildProc  function,  886 
DEFPUSHBUTTON  statement,  413-14,  431 
DefWindowProc  function,  25,  37,  51-52, 
146.  See  also  DefFrameProc  function 
deinitialization,  DLL,  918 
delayed  rendering,  811-12 
DeleteAtom  function,  830 
DeleteDC  function,  386 
DeleteMenu  function,  367 
DeleteMetaFile  function,  647,  649,  656 
DeleteObject  function,  245,  387,  388, 
546-49,  586 

DESCRIPTION  statement,  39 
descriptor  tables,  275-76 
DestroyCaret  function,  118-19 
DestroyMenu  function,  345,  369 
DestroyWindow  function,  42, 148,  447 
DEVCAPS1  example  program,  498-512 
DEVCAPS2  example  program,  737-47 
device  contexts 
attributes,  514-15 
display  color  information,  513-14 
display  size  information,  512-13 
example  program  displaying 
information  about,  498-512 
handles,  26,  50-54,  496-97 
information,  204,  498,  508-9 
mapping  modes  (see  mapping  modes) 
memory  (see  memory  device  contexts) 
overview,  38,  495-96 
printer  (see  printer  device  contexts) 
raster  capability  identifiers,  510,  511 ,  111 
saving,  515-17 
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device  coordinates 

converting  between  logical  coordinates 
and,  520-22 

logical  coordinates  vs.,  519 
systems  of,  519-20 
viewport  and,  520 
virtual  coordinates  vs.,  494 
device  dependency  problems,  549 
device-dependent  bitmap  format,  619-23 
device  fonts,  667-68 
device-independent  bitmap  (DIB)  format 
creating,  618-19 
disk  file  format,  607-9 
example  program  displaying,  610-18 
packed-DIB  format,  609-10 
device-independent  graphics  interface.  See 
Graphics  Device  Interface  (GDI) 
DeviceMode  function,  745-46 
DGROUP  segment  (local  memory),  281-82 
diacritics,  92, 111-12 
dialog  boxes 

library  (see  common  dialog  box  library) 
message  boxes  as  alternatives  to, 

443-45  (see  also  message  boxes) 
modal  (see  modal  dialog  boxes) 
modeless  (see  modeless  dialog  boxes) 
overview,  407-8 
for  printing,  763-68 
procedure,  414-16 
system  modal,  and  mouse  messages, 
137-38 

DialogBox  function,  416-17 
DIALOG  statement,  413-14 
DIB.  See  device-independent  bitmap 
(DIB)  format 

DIF.  See  Data  Interchange  Format  (DIF) 
DIGCLOCK  digital  clock  example 
program,  199-206 
directives,  preprocessor,  308 
discardable  memory,  279,  288,  296 
Dispatch  Message  function,  24,  35-36 


display  count,  mouse  cursor,  154 
display  devices 

coordinates  (see  device  coordinates) 
device  contexts  (see  device  contexts) 
example  program  displaying 
information  about,  498-512 
graphics  (see  graphics;  Graphics  Device 
Interface  (GDI)) 
information  about,  498 
painting  text  on  (see  text  output) 
printer  devices  vs.,  729-30 
raster  vs.  vector,  494 
types  of,  186,  313-14,  413,  512,  514 
Windows  color  and,  186  (see  also  colors  i 
dithered  colors,  186,  552,  572 
DLG  extension.  See  dialog  boxes 
DLL.  See  dynamic  link  libraries  (DLLs) 
documents,  multiple.  See  Multiple 
Document  Interface  (MDI) 
documents,  printing  multipage,  768-75 
DOS3Call  function,  463 
dot-matrix  printer,  banding  for,  779-80. 

See  also  printer  devices 
double-clicks,  mouse,  145 
DPtoLP  function,  521-22,  543 
DrawBitmap  example  function,  631-32 
Drawlcon  function,  317,  592 
drawing  graphics.  See  graphics 
drawing  modes,  550-52 
drawing  text.  See  text  output 
DRAWITEMSTRUCT  data  structure, 

213,  232 

DrawMenuBar function,  367-68 
DrawText  function,  25,  38-39,  234,  325, 
327,  661-62 

draw  text  (DT)  identifiers,  25,  38-39, 

234,  661-62 
drivers 

hardware  timer  interrupt,  177-78 
keyboard,  90-91 
mouse,  908 
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DS  register,  929-34 

DT  (draw  text)  identifiers,  25,  38-39,  234, 
661-62 

dynamic  data  exchange  (DDE).  See  also 
DDE  Management  Library  (DDEML) 
applications,  topics,  and  items,  824-25 
character  strings  and  atoms,  830-31 
client  cancellation  of  data  update 
requests,  854 

client  data  requests,  849-50 
client  data  update  requests,  851-53 
client  initiation  of  conversations, 

847- 48,  864-65 
client  receipt  of  data,  865 

client  termination  of  conversations,  854 
conversation  types,  825-30 
data  structures,  830 
example  client  program,  854-66 
example  server  program,  831-54 
functions  ( see  DDE  Management  Library 
(DDEML)) 

global  memory  functions  and,  292 
identifiers,  866,  879-81 
overview,  823-24 
server  child  window  procedures, 

848- 49 

server  data  messages,  850-51 
server  data  updates,  853-54 
server  termination  of  conversations,  866 
dynamic  link  libraries  (DLLs) 
batch  files,  912-13 
C++  name-mangling  and,  918-19 
call-back  functions,  928-29 
compiling,  912-13 
creating  and  using  import  libraries, 
936-38 

deinitialization  routines,  918 
dynamic  linking  vs.  static  linking,  907 
dynamic  linking  without  imports, 
938-39 


dynamic  link  libraries  (DLLs),  continued 
entry  point  functions,  916-17 
examining,  with  EXEHDR  program, 
909-10 

example  program  with,  911-12,  920-29 
example  program  with  resource -only, 
940-45 

example  string  library,  911-12,  913-16, 
919 

far  function  prologs  and  exported 
functions,  927-28 
linking  options,  23 
link  specification  methods,  935-36 
memory  usage,  8-9,  929-34 
module  definition  files,  919-20 
object  libraries  and  import  libraries  vs., 
908-9 

overview,  8, 12-13,  907-10 
resource- only,  939-45 
restrictions,  934-35 

E 

edit  controls 

example  program,  247-49 
message  identifiers,  252,  403,  774 
notification  identifiers,  251 
overview,  246-47 
style  identifiers,  250 
window  subclassing  and,  251 
edit  message  (EM)  identifiers,  252,  403,  774 
edit  notification  (EN)  identifiers,  251 
editors.  See  Image  Editor;  text  editor 
example  program 
edit  style  (ES)  identifiers,  250 
EGA.  See  Enhanced  Graphics  Adapter 
Ellipse  function,  560-61 
ellipses  as  clipping  regions,  587-92 
elliptical  lines,  542,  544 
EM  (edit  message)  identifiers,  252,  403,  774 
Empty  Clipboard  function,  794,  796,  809-10 
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EnableMenuItem  function,  354,  368 
EnableWindow  function,  219,  435,  760-61 
ENDDOC  subfunction  of  Escape ,  730-31, 
748 

EndPaint  function,  25,  38,  51-52,  496 
Enhanced  Graphics  Adapter  (EGA),  186, 
313-14,  512 
enhanced  mode,  273 
EN  (edit  notification)  identifiers,  251 
entry  points 
library,  916-17 
program,  24,  28-29 
EnumClipboardEormats  function, 

810-11,  815 

enumerating  fonts,  700-14 
EnumFonts  function,  700-14 
EnumFunction  function,  701 
EnumMetaFile  function,  657 
ENVIRON  example  program,  258-61 
environment  variables,  19,  258-61,  912-13 
epilog  code,  191 
error  handling,  printer,  776-77 
error  messages,  example  program 
displaying,  326 

Escape  function,  730-34,  747-48 
escapement  of  text,  692-93 
ES  (edit  style)  identifiers,  250 
ExcludeClipRect function,  587 
EXE  files,  Windows  format,  12.  See  also 
compiling 

EXEHDR  program,  909-10 
EXETYPE  statement,  39 
expanded  memory,  9 
exported  far  functions.  See  call-back 
functions 

EXPORTS  statement,  935 

extended  character  sets,  127, 128-29, 133 

extended  key  flag,  keystroke,  95 

extended  memory,  9 

extents,  window  and  viewport,  521 

extern  statement,  919 


ExtFloodFill  function,  592 
ExtTextOut  function,  66l 

F 

far  addresses,  274-75 
y^rfunctions 

exported  (see  call-back  functions) 
pascal  keyword  and,  12 
Prologs,  191,  927-28 
FAR  PASCAL  functions,  191 
far  pointers,  274-75 
FARPROC  type,  188 
FAR  type,  26 

FF  (font  family)  identifiers,  671,  696 
figures.  See  filled  areas 
File  Formats  for  Popular  PC  Software 
(Walden),  793 
FileOpen  function,  463 
files 

attribute  codes,  261-62 
batch,  for  setting  environment  variables, 
19,  912 

bitmaps  in  (see  device-independent 
bitmap  (DIB)  format) 
converting  names  and  contents  of, 
between  character  sets,  133 
example  program  for  listing  and 
displaying,  263-68 
example  program  with  file  handling, 
466-88 

example  program  with  user-defined 
resource  for,  329-37 
font  resource,  667-68,  674-75 
GDI  drawing  functions  in  (see  metafiles^ 
input  and  output  functions,  463-66 
input  and  output  methods,  461-63 
listing,  463 

listing,  in  list  boxes,  261-68 
make  files  (see  make  files) 
module  definition  (see  module 
definition  files) 


958 


Index 


files,  continued 

multiple  documents  (see  Multiple 
Document  Interface  (MDI)) 
open  file  identifiers,  464 
open  file  name  data  structure,  486 
open  file  name  identifiers,  486-87 
printing  multipage  documents,  768-75 
resource  (see  resources) 
search  and  replace  functions,  487-88 
filled  areas 

bitmap  brushes,  575-79 
bounding  boxes,  559-63 
brush  alignment,  580-82 
brushes,  572-74 

example  program  drawing  arcs,  563-68 
overview,  558-59 
pie  charts,  569-71 
polygons,  571-72 

FillRect  function,  186,  583,  627-28 

FillRgn  function,  585-86 

FindAtom  function,  830 

FINDREPLACE  data  structure,  487-88 

FindResource  function,  328,  655 

FindText  function,  487-88 

fixed  memory  segments,  278-79 

fixed-pitch  fonts,  66,  671 

flags.  See  identifiers;  switches,  compiling 

floating  popup  menus,  357-63 

FloodFill  function,  592 

_ fmalloc  function,  303 

font  family  (FF)  identifiers,  671,  696 

FONTLIST  example  program,  702-14 

fonts 

bitmaps  and,  385-86 
character  sets  and,  130  (see  also 
character  sets) 
character  size,  57,  232 
data  structures,  385,  692-96,  724-27 
enumerating,  700-714 
example  program  enumerating,  702-14 


fonts,  continued 

example  program  with  selection  of, 
725-27 

fixed-pitch  vs.  variable-width,  66 

GDI  vs.  device,  667-70 

leading  and  spacing,  677-78 

logical  (see  logical  fonts) 

logical  inches,  676-77 

logical  twips  mapping  mode,  678-79 

point  sizes,  675-77 

printer  devices  and,  786-88 

resource  files,  674-75 

selection  identifiers,  786 

stock,  117, 130,  663-64 

system,  47,  56, 130 

terminal,  130 

text  metrics  information,  57-58 
TrueType  (see  TrueType  fonts) 
typeface  families,  670-74 
variable-width  vs.  fixed-pitch,  66 
weight  identifiers,  694 
FONT  statement,  418 
foreign  languages.  See  international 
support 
formatting  text 

character  dimensions,  58-60 
example  program  with  paragraph 
justification,  716-25 
one-line  alignment,  715-16 
overview,  714 

FORMFEED  example  program,  748-51 
FrameRect  function,  583 
FrameRgn  function,  585-86 
frame  window  procedures,  903-4 
frame  windows,  MDI,  885 
free  function,  303 
FreeLibrary  function,  746,  939 
FREEMEM  example  program,  193-99 
free  memory,  193-99 
FreeProcInstance  function,  761 
FreeResource  function,  329 
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functions.  See  also  window  procedures 
aliases,  935-36 

call-back  (see  call-back  functions) 
calling  MS-DOS,  from  Windows,  463 
caret,  118-19 

C  language  memory  allocation,  303 

clipboard,  816-18 

coordinate  systems  and,  519-20 

device  context  attributes  and,  514-15 

dialog  box,  435 

file  I/O,  463-66 

global  memory,  291-95 

in  HELLOWIN  example  program,  24-25 

libraries  of  (see  libraries) 

local  memory,  298-301 

menu,  367-69 

program  entry  point,  24,  28-29 
prologs,  191,  927-28 
syntax  of,  11-12 

FW  (font  weight)  identifiers,  694 

G 

GDI.  See  Graphics  Device  Interface 
GDI  library,  12,  908,  936. 

GDT.  See  global  descriptor  tables 
generic  handle,  26 
GetAsyncKeyState  function,  99 
GetAtomName  function,  830-31 
GetBitmapBits  function,  576,  621 
GetBitmapDimension  function,  623 
GetBitmapFont  function,  385,  388 
GetBkColor function,  550 
GetBkMode  function,  550 
GetBValue  macro,  186 
GetCaretBlinkTime  function,  118 
GetCaretPos  function,  118 
GetClassName  function,  813 
GetClassWord function,  244 
GetClientRect  function,  24,  38,  435 
GetClipboardData  function,  795-97,  810, 
813-15 


GetClipboardFormatName  function,  815 
GetClipboardOwner function,  813 
GetClipboard Viewer  function,  817 
GetCurrentPosition  function,  543 
GetCurrentTime  function,  206 
GetCursorPos  function,  155 
GetDC function,  54,  496,  497 
GetDeviceCaps  function,  498-514,  737-47 
GetDialogBaseUnits  function,  232,  413 
GetDIBits  function,  619 
GetDlgltem  function,  429 
GetFreeSpace  function,  199 
GetGValue  macro,  186 
GetlnstanceData  function,  283,  336 
GetKeyState  function,  98-99, 144-45 
GetMapMode  function,  518 
GetMenu  function,  354 
GetMenuItemCount  function,  368 
GetMenuItemID  function,  368 
GetMenuState  function,  369 
GetMenuString  function,  368,  745 
GetMessage  function 

dynamic  link  libraries,  934 
keyboard  input,  90 
locking  data  segments,  301 
nonpreemptive  multitasking  with, 
43-44 

overview,  24,  35 

GetMessageTime  function,  93, 145,  206 
GetMetaFileBits  function,  655 
GetMetaFile  function,  649 
GetNearestColor function,  514 
GetNextDlgGroupItem  function,  434 
GetNextDlgTabltem  function,  434 
GetObject function,  385,  386,  547 
GetOpenFileName  function,  486 
GetParent  function,  207 
GETPHYSPAGESIZE  subfunction  of  Escape 
748,  787 

GetPixel  function,  542 
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GetProcAddress  function,  746,  939 
GetProfilelnt  function,  205 
GetProfileString  function,  205,  509, 

735-37 

GetROP2  function,  551 
GetRValue  macro,  186 
GetSaveFileName  function,  486 
GetScrollPos  function,  70 
GetScrollRange  function,  70 
GetStockObject  function 
brushes,  31,  224 
fonts,  117,  385,  663-64 
OEM  character  set,  130 
overview,  24 
pens,  545 

GetSubMenu  function,  363,  368 
GetSysColor function,  221-22 
GetSystemMenu  function,  367,  388 
GetSystemMetrics  function,  60-65, 135, 

235,  313,  519 

GetTempFileName  function,  648 
GetTextColor function,  662 
GetTextExtent  function,  386,  664,  714-16, 
787-88 

GetTextFace  function,  681,  698 
GetTextMetrics  function,  57,  519,  664, 

681,  698 

GetUpdateRect  function,  50,  586 
GetViewportOrg  function,  524 
GetWindowDC function,  496-97 
GetWindowLong  function,  243 
GetWindowOrg  function,  524 
GetWindowRect  function,  232 
GetWindowText  function,  218 
GetWindowTextLength  function,  219 
GetWindoivWord  function,  166,  214,  429 
GHND  flag,  293,  795 
GlobalAddAtom  function,  831 
GlobalAlloc  function,  286,  291-92,  297-98, 
303,  793 


GlobalAllocPtr  macro,  291,  293 
GlobalCompact  function,  199,  294 
GlobalDeleteAtom  function,  831 
global  descriptor  tables  (GDT),  276 
GlobalDiscard  macro,  295 
GlobalFindAtom  function,  831 
GlobalFlags  function,  296 
GlobalFree  function,  291,  294 
GlobalFreePtr  macro,  291,  294 
GlobalGetAtomName  function,  831 
GLOBALHANDLE  type,  290 
GlobalLock  function,  291,  293,  296, 

297-98,  793 

global  memory.  See  also  segments,  memory 
allocation  (see memory  allocation) 
discardable,  296 

fixed  and  moveable  segments,  278-79 
free,  193-99 
functions,  291-95 
huge  blocks  of,  296-98 
identifiers,  292,  295-96 
layout,  279-81 
local  memory,  281-82 
terminology,  277-78 
GlobalPtrHandle  macro,  294 
GlobalReAlloc  function,  294-95,  796 
GlobalReAllocPtr  macro,  295 
GlobalSize  function,  294 
GlobalUnlock  function,  291,  293-94, 

296,  793 

GMEM  (global  memory)  identifiers,  292, 

295,  296 
GPTR  flag,  293 

GRAFMENU  example  program,  374-89 
graphical  user  interface  (GUI) 
concepts  and  rationale,  5-6 
consistency,  6-7,  355 
Windows  as,  5 
graphics 

clipping,  rectangles,  and  regions,  583-92 
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graphics,  continued 

controls  ( see  child  window  controls) 
example  program  that  draws  forever, 
598-603 

filled  areas,  558-82 
functions,  592-98 
lines,  542-57 
points,  541-42 

printing,  751-77  (see  also  printing) 
rectangles,  regions,  and  clipping,  583-92 
resources  (see  bitmaps;  icons;  mouse 
cursors) 

Graphics  Device  Interface  (GDI) 
character  size,  57 
client-area  size,  67-68 
coordinates  (see  coordinates) 
device  contexts  (see  device  contexts) 
display  devices  (see  display  devices) 
drawing  graphics  (see  graphics) 
fonts  (see  fonts) 

mapping  modes  (see  mapping  modes) 
metafiles  (see  metafiles) 
objects  (see  bitmaps;  brushes;  logical 
fonts;  pens;  regions) 
paint  information  structure,  52-54  (see 
also  PAINTSTRUCT  data  structure) 
painting  text  (see  text  output) 
philosophy,  493-95 
printer  devices  (see  printer  devices) 
user  advantages,  9-10 
GrayString  function,  664-66 
group  boxes,  218 
group  window  style,  432-34 
GUI.  See  graphical  user  interface 

H 

h alloc  function,  303 
handles 
brush,  26 

device  context,  26,  50-54,  496-97 
generic,  26 


handles,  continued 
icon,  26,  315-17 
mouse  cursor,  26 
overview,  27 
parent  window,  33,  207 
program  instance,  28,  31,  33 
types  (see  handle  types) 
window,  26,  33 
window  menu,  33 
HANDLE  type,  26 
handle  types.  See  also  data  types 
bitmap,  575 
brush,  558 
cursor,  172,  318 
device  context,  51 
icon,  315 
memory,  290 
names,  26-27 
pen, 545 
window,  33 

hardware  interrupts.  See  interrupts 
hatch  style  (HS)  identifiers,  573 
HBITMAP  type,  575 
HBRUSH  type,  26,  558 
HCURSOR  type,  26,  172,  318 
HDC  type,  26,  51 
header  files,  308 

HEAD  example  program,  263-68 
heap.  See  global  memory;  local  heap 
HEAPSIZE  statement,  40,  281,  920 
HELLOWIN  example  program,  15-40 
HEXCALC  example  program,  454-61 
HICON  type,  26,  315 
HideCaret  function,  118-19 
HiliteMenuItem  function,  368 
hit-testing 

child  windows  and,  160-61 
example  program  with  child  windows, 
161-67 

example  program  with  keyboard 
interface,  155-60 
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hit-testing,  continued 

example  program  with  simple,  150-54 
hypothetical  example,  149 
identifiers,  146-48 
keyboard  emulation  of  mouse  and, 
154-55 

nonclient-area,  147-48 
HI  WORD  macro,  137,  543 
horizontal  scrolling  program,  79-85 
hot  links,  827-28,  851-54 
hourglass  mouse  cursor,  136 
HPEN  type,  545 
HS  (hatch  style)  identifiers,  573 
HT  (hit-test)  identifiers,  146-48 
huge  memory  blocks,  296-98 
huge  memory  model,  282-83 
huge  pointers,  297 
Hungarian  notation,  27-28 
HWND  type,  26,  33 

I 

IBM  8514/A  video  adapter,  313-14,  512,  514 
IBM-compatible  computers,  5 
IBM  Enhanced  Keyboard,  95 
IBM  extended  character  set,  128-29 
IBM  video  adapters.  See  Color  Graphics 
Adapter  (CGA);  Enhanced  Graphics 
Adapter  (EGA);  IBM  8514/A  video 
adapter;  Video  Graphics  Array  (VGA) 

icons 

creating  customized,  with  Image  Editor, 
197,  313-15 
customized,  317 

determining  status  of  applications 
as,  198 

displaying  windows  as,  33 
drawing,  with  applications,  197-98 
example  program  with  customized, 
309-12 

handles,  26,  315-17 


icons,  continued 

identifiers,  25,  31,  280 
ID  number  macro,  316 
input  focus  and  active  window  as,  92 
maintaining  windows  as,  199 
minimizing  windows  to,  198 
NULL,  197-98,  246 
ICON  statement,  319,  413 
IDC  (cursor)  identifiers,  25,  31, 136 
identifiers 

binary  raster  operation  (ROP2),  550-57 

brush  style,  574 

button  message,  215-16 

button  notification,  215 

button  style,  212-18 

child  window  control  color,  223 

choose  font,  786 

class  style,  25,  30, 145,  516-17 

clipboard  format,  792-93,  813-14 

color  control,  223 

create  window,  25,  33 

cursor,  25,  31, 136 

data  exchange,  866,  879-81 

data  structure  (see  data  structures) 

data  type,  25-26, 143, 188,  290 

draw  text,  25,  38-39,  234,  661-62 

edit  message,  252,  403,  774 

edit  notification,  251 

edit  style,  250 

exchange,  866,  879-81 

font  family,  671,  696 

font  selection,  786 

font  weight,  694 

global  memory,  292,  295,  296 

handle  type  (see  handle  types) 

hatch  style,  573 

hit-test,  146-48 

icon,  25,  31,  280 

list  box,  261-63,  463 

list  box  notification,  257 
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identifiers,  continued 

list  box  style,  254-57,  262-63 

local  memory,  299 

logical  font,  692-96 

mapping  mode,  55,  518-19,  522-34 

menu  flag,  346-47,  368-69 

message  box,  280,  444 

mouse  button,  98,  99, 136 

mouse  cursor,  25,  31, 136 

mouse  hit-test,  146-48 

mouse  key,  137 

open  file,  464 

open  file  name,  486-87 

output  font,  695 

pen  style,  546-48,  560 

prefixes  for  uppercase,  25 

raster  capability,  510,  511 ,  111 

raster  operation  (ROP),  626,  630 

region,  585 

scroll  bar,  71-73,  242 

scroll  bar  style,  234-35 

show  window,  24,  33-34,  43, 198,  204 

spool,  750,  757-59,  776-77 

static  style,  233-34 

stock  font,  664 

system  color,  221-22,  233 

system  command,  347,  367 

system  metrics,  313,  549 

text  alignment,  660 

types  of,  25 

virtual  key,  95-99, 144-45,  392 
window  class  style,  25,  30, 145,  516-17 
window  message  (seeWM  (window 
message)  identifiers) 
window  size,  41 

window  style  ( see  window  style  (WS) 
identifiers) 

IDI  (icon)  identifiers,  25,  31,  280 
Image  Editor,  197,  313-15 
IMPLIB  program,  936-37 


IMPORT.LIB  library,  909,  936 
import  libraries 

creating  and  using,  936-38 
dynamic  linking  without,  938-39 
linking  with,  13,  908-9 
IMPORTS  statement,  935-37 
inch.  See  logical  inch 
InflateRect  function,  584 
information  device  contexts,  204,  498, 
508-9 

initialized  static  data  memory,  281 
input.  See  child  window  controls; 

keyboard;  mouse;  timer 
input  focus 

buttons  and,  219-20 
caret  display  and,  118-19 
keyboard  messages  and,  91-92 
scroll  bars,  242-43 
input/output  for  files 
functions,  463-66 
methods,  461-63 
InsertMenu  function,  367,  384 
instances,  program 
handles,  28,  31,  33 
multiple,  246 
overview,  8,  28 
thunks,  192,  278,  910 
instance  segment  attribute,  288 
integer  types,  26 

Intel  microprocessors.  See  microprocessors 
interfaces.  See  graphical  user  interface 
(GUI);  Graphics  Device  Interface 
(GDI);  keyboard  interfaces;  Multiple 
Document  Interface  (MDI) 
international  support 
character  sets,  131-33 
date  and  time  formats,  205-6 
diacritics,  92, 111-12 
keyboard  drivers,  90-91 
MS-DOS,  129, 132-33 


964 


Index 


interrupts 
keyboard,  90 

messages  vs.  hardware,  43,  90 
timer,  177-79 

IntersectClipRect  function,  587 
IntersectRect  function,  584 
InvalidateRect  function,  49-30,  586 
InvalidateRgn  function,  49,  586 
invalidating  rectangles  and  regions, 

49-50,  586 

InvertRect function,  583,  628 
InvertRgn  function,  585-86 
IsClipboardFormatAvailable  function, 
403,  794,  810 

IsDialogMessage  function,  446-47,  453 
IsDlgButtonChecked function,  430 
Islconic  function,  198 
isotropic  mapping  mode,  528-33 
IsRectEmpty  function,  584 
IsWindowEnabled  function,  219 
IsWindowVisible  function,  219 
italic  characters,  694 

J 

JUSTIFY  example  program,  716-25 

K 

Kernighan,  Brian,  15 

keyboard.  See  also  Alt  key;  Ctrl  key; 

Shift  key 

accelerators  ( see  keyboard  accelerators) 
characters  vs.  keystrokes,  92  ( see  also 
character  messages;  keystroke 
messages) 
drivers,  90-91 

emulating  mouse  with,  154-55 
generating  OEM  codes  from,  133 
ignoring  input  from,  91 
input  focus  and,  91-92 
interfaces  ( see  keyboard  interfaces) 


keyboard,  continued 

keystrokes  vs.  characters,  92  ( see  also 
character  messages;  keystroke 
messages) 
overview,  89-92 
Tab  key  logic,  432-34 
keyboard  accelerators 

example  program,  395-405 
loading  tables  of,  393 
message  processing,  394-95,  403-5 
overview,  91,  389-90 
rules  on  assigning,  390-91 
tables  in  resource  scripts,  391-93 
translating  keystrokes,  393-94 
uses  for,  390 

KEYBOARD.DRV  driver,  90-91,  908 
keyboard  interfaces 

automatic,  with  scroll  bar  controls, 
242-43 

for  bitmap  menu  items,  389 
for  dialog  boxes,  432-34 
mouse  message  processing,  155-60 
scrolling,  85, 100-108 
KEYLOOK  example  program,  112-18 
keystroke  messages.  See  also  keyboard 
character  messages  vs.,  92  ( see  also 
character  messages) 
example  program,  100-108 
example  text  editor  program,  119-27 
iParam  variable  flags,  94-95 
processing,  99-100 
as  queued  messages,  42 
Shift  key  states,  98-99 
Shift  key  states  and  mouse  messages, 
144-45 

system  and  nonsystem,  93-94 
translating,  for  keyboard  accelerators, 
393-94 

translating,  into  character  messages, 
35, 108-11 

virtual  key  codes,  95-99 
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KillTimer  function,  177,  179 
KRNL286  and  KRNL386  libraries,  12, 

908,  936 

L 

landscape  mode,  743,  780 
large  memory  model,  282-83,  285-86 
laser  printers,  668,  780.  See  also  printer 
devices 

LB  (list  box)  identifiers,  261-63,  463 
LBN  (list  box  notification)  identifiers,  257 
LBS  (list  box  style)  identifiers,  254-57, 
262-63 

-Iclose  function,  463,  466 
-lereat  function,  463,  464-65 
LDT.  See  local  descriptor  tables 
leading  of  fonts,  677-78 
learning  curve  for  programming,  44-45 
least  recently  used  (LRU)  algorithm,  279 
LHND  flag,  299 
LibEntry  function,  917 
LIB. EXE  program,  937 
LibMain  function,  916-17 
libraries.  See  also  DDE  Management 
Library  (DDEML);  dynamic  link 
libraries  (DLLs);  functions 
examining,  909-10 

linking  and,  907-8  ( see  also  compiling) 
make  files  and,  23 
types  of,  908-9 
LIBRARY  statement,  919 
LIBW.LIB  library,  23,  909,  936 
LINEDDA  example  program,  594-98 
LineDDA  function,  593-98 
lines 

color  and  drawing  modes,  556-57 
device  dependency  problems,  549 
dotted  and  dashed  pen  gaps,  549-50 
drawing  modes,  550-52 
example  program  with  drawing-mode 
codes,  552-56 


lines,  continued 
overview,  542-44 
stock  pens,  544-45 
user-defined  pens,  545-49 
line  spacing  of  fonts,  677-78 
LineTo  function,  141,  542,  544 
LINK.EXE  linker,  23 
links,  DDE.  See  conversations,  DDE 
links,  DDL,  935-36.  See  also  dynamic  link 
libraries  (DLLs) 
list  box  controls 

example  program  listing  environment 
variables,  258-61 

example  program  listing  files,  263-68 
identifiers,  261-63,  463 
inserting  strings,  254-55 
listing  files,  261-63 
notification  identifiers,  257 
receiving  messages  from,  257 
selecting  and  extracting  entries,  255-57 
style  identifiers,  253-57,  262-63 
-llseek function,  463 
LMEM  (local  memory)  identifiers,  299 
LoadAccelerators  function,  393 
LoadBitmap  function,  324,  384,  575 
LoadCursor function,  24,  31, 136,  318 
Loadlcon  function,  24,  31,  315-17 
LoadLibrary  function,  746,  939 
LoadMenu  function,  345,  387 
LoadMenuIndirect function,  357 
LoadResource  function,  328,  655 
load  segment  attribute,  287-88 
LoadString  function,  325-27,  336 
LocalAlloc  function,  299-303 
LocalCompact  function,  301 
local  descriptor  tables  (LDT),  276 
LocalDiscard  function,  301 
LocalFlags  function,  301 
LocalFree  function,  299-300 
LocalFreeze  function,  301 
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LOCALHANDLE  type,  290 
local  heap 

organization,  281-82 
size,  40,  281,  920 
LocalLock  function,  299-300 
LocalMelt  function,  301 
local  memory  (DGROUP  segment) 
functions,  298-301 
identifiers,  299 
organization,  281-82 
LocalReAlloc  function,  301-2 
LocalSize  function,  301 
localtime  function,  204 
LocalUnlock  function,  299-300 
LockData  function,  302 
locking  memory 

data  segments,  301-2 
memory  blocks,  289-91 
LockResource  function,  329,  655 
LOGBRUSH  data  structure,  574,  579 
LOGFONT  data  structure,  385,  692-96 
logical  brushes,  574,  579 
logical  coordinates 

converting  between  device  coordinates 
and,  520-22 

device  coordinates  vs.,  519 
mapping  modes  and,  55 
logical  fonts 

creating,  selecting,  and  deleting,  679-81 
example  program  comparing  real  and, 
681-92 

identifiers,  671,  692-96 
information  about,  698-700 
mapping,  696-98 
structure,  385,  692-96 
logical  inch,  513,  676-77 
logical  pens,  545-49-  See  also  pens 
logical  twips,  676,  678-79 
LOGPEN  data  structure,  547 
long  pointers,  274-75 
LONG  type,  26 


-lopen  function,  463,  464 
LOWORD  macro,  137,  543 
iParam  message  parameter 
character  messages,  109 
client-area  size  messages,  68 
example  program  displaying,  209-20 
keystroke  messages,  94-95 
mouse  messages,  137, 142-43, 146 
overview,  35,  41-42 
scroll  bars  and  scroll  bar  controls,  234 
LPSTR  type,  26 
LPtoDP  function,  522,  582 
LPTR  flag,  299,  302-3 
-tread function,  463,  466 
-Iseek  function,  463,  465 
Istrcatt unction,  466 
Istrcmp  function,  466 
Istrcpy  function,  466,  795 
Istrlen  function,  466 
-Iwrite  function,  463,  465-66 

M 

macros 

coordinate  conversion,  143,  543 
coordinate  extraction,  137,  543 
memory  allocation,  291,  293-95 
resource  ID  number,  316,  345 
RGB  color  values,  185-86,  542 
scroll  bar  limits,  77 
make  files.  See  also  compiling 
for  compiling  resources,  307-8 
for  dynamic  link  libraries,  912-13 
for  Microsoft  C/C++  and  Borland  C++, 
21-24 

setting  environment  variables  for,  19, 
912-13 

MAKEINTRESOURCE  macro,  316,  345 
MAKEPOINT  macro,  143,  543 
MakeProcInstance,  188, 192,  287,  760-61 
MAKE  utility,  19,  21-24 
malloc  function,  281-82,  303 
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MapDialogRect  function,  435 
mapping  modes 

anisotropic,  533-34 
conversions,  639-40 
device  coordinates  vs.  logical 
coordinates,  519 

device  coordinate  systems,  519-20 
example  program  with  various,  534-39 
identifiers,  55,  518-19,  522-34 
isotropic,  529-33 
isotropic  vs.  anisotropic,  528-29 
logical  coordinates,  55 
logical  coordinates  vs.  device 
coordinates,  519 
metafile  pictures  and,  805-9 
metric,  525-28 
overview,  517-19 
text,  522-25 
user-defined,  528-34 
viewport  and  window  terminology, 
520-22 

MATHWS  and  MATHWM  files,  283 
max  macro,  77 

MB  (message  box)  identifiers,  280,  444 
MDI.  See  Multiple  Document  Interface 
MDICLIENT  window  class,  886 
MDICREATESTRUCT  data  structure, 
886-87,  902-3 

MDIDEMO  example  program,  887-902 
medium  memory  model,  282-85 
memory 

allocation  {see  memory  allocation) 
character  string  resources  and,  326-28 
clipboard’s  use  of,  795-96 
free,  193-99 

management  {see  memory  management) 
microprocessors  and,  272-76,  929-34 
near  and  far  addresses,  274-75 
organization  {see  segments,  memory) 
protected  mode  and,  275-76 
resources  and,  319-24 


memory  allocation 

C  language  functions,  303 
discardable  global  memory,  296 
example  of  locking  memory  blocks, 
290-91 

global  memory  functions,  291-95 
global  vs.  local  heap,  289 
huge  global  memory  blocks,  296-98 
local  memory  functions,  298-301 
local  vs.  global  heap,  289 
locking  data  segments,  301-2 
locking  memory  blocks,  289-91 
macros,  291,  293-95 
shortcuts,  302-3 

memory  device  contexts,  384-85,  623-25, 
634-38 

memory  management 

code  and  data  segments,  282-89 
dynamic  link  libraries,  929-34 
features  of  Windows  versions,  271-73 
memory  models  and,  282-83,  285-86 
movement  problems,  286-87 
multiple  code  segments,  283-85 
segment  attributes,  287-89 
user  advantages,  8-9 
wasted  buffer  space,  268 
memory  models 

compact  and  large,  285-86 
medium,  283-85 
mixed,  283 

Windows-supported,  282-83 
memory  segment  attribute,  288 
MENUDEMO  example  program,  348-55 
MENUITEM  SEPARATOR  statement,  343 
MENUITEM  statement,  343-44 
MENUITEMTEMPLATE  data  structure,  357 
menus 

bitmap  images  in,  374-89 
consistency  issues,  355 
creating,  from  bitmaps,  387-89 
creating,  from  data  structure,  357 
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menus,  continued 

creating,  within  programs,  355-57 
data  structure,  357 
destroying  multiple  MDI,  906 
enabling  and  graying  options  in,  403 
example  program  using  system,  363-67 
example  program  with  bitmaps  in, 
374-89 

example  program  with  floating  popup, 
358-63 

example  program  with  keyboard 
accelerators  for,  396-405 
example  program  with  multiple 
top-level,  369-74 

example  program  with  simple,  348-55 
floating  popup,  357-63 
functions  for  manipulating,  367-69 
handles,  33 

ID  number  macro,  345 
keyboard  interface  for,  with 
bitmaps,  389 

MDI  and  multiple  templates  for, 

900-901 

message  processing,  346-48 
processing  options  in,  403-5 
referencing,  in  programs,  344-45 
selection  identifiers,  346-47,  368-69 
structure,  340 
system,  363-67 

templates  in  resource  scripts,  340-44 
terminology,  339-40 
MENU  statement,  341,  418 
MessageBeep  function,  182 
message  boxes 

creating,  as  alternatives  to  dialog  boxes, 
443-45 

identifiers,  280,  444 
informative,  181-82,  444-45 
system  modal,  and  mouse  messages, 
137-38 


MessageBox function,  181,  325,  326,  443-45 
message-driven  architecture,  13-14 
message  loop,  15,  34-36 
message  queue,  15,  34 
messages 

character  ( see  character  messages) 
between  child  and  parent  windows, 
214-16 

clipboard,  816-18 
color,  223-25 
data  structure,  26,  34-35 
DDE  server  data,  850-51 
default  processing  ( see  DefWindotuProc 
function) 

to  edit  controls,  252 
error,  326 

identifiers  (s^WM  (window  message) 
identifiers) 
interrupts  vs.,  43,  90 
keyboard  accelerator,  394-95,  403-5 
keystroke  ( see  keystroke  messages) 
from  list  boxes,  257 
loops,  15,  34-36 
MDI  frame  window,  903-4 
menu,  346-48 

mouse  ( see  mouse  messages) 
object-oriented  programming  and,  13 
overview,  13-14 

paint/repaint  (see  WM_PAINT  message) 
parameters,  35,  36  (see  also  iParam 
message  parameter;  wParam  message 
parameter) 
posting,  43 
processing,  36-37 
queue,  15,  34 

queued  and  nonqueued,  42-43 
retrieving,  with  loop,  15,  34-36 
scroll  bar,  71-73 

sending  (see  SendMessage  function) 
timer  (see  timer) 

Windows  architecture  and,  13-14 
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METAFILEPICT  data  structure,  805-9 
metafiles 

bitmaps  vs.,  605-6  ( see  also  bitmaps) 
clipboard  transfers,  804-9 
disk,  647-49 

GDI  functions  not  allowed  in,  657-58 
memory,  646-47 
overview,  645-46 
picture  data  structure,  805-9 
playing,  658 
preexisting,  649-52 
as  resources,  652-56 
structure,  656-57 
metric  mapping  modes,  525-28 
metrics,  text.  SeeTEXTMETRIC  data 
structure 

MFCREATE  example  program,  649-52 
MF  (menu  flag)  identifiers,  346-47, 
368-69 

MFRESORC  example  program,  652-56 
microprocessors 

dynamic  link  libraries  and,  929-34 
memory  and,  272-76 
near  addresses  and  far  addresses, 
274-75 

protected  mode,  275-76 
Windows  versions  and,  4 
Microsoft  C/C++  7.0, 19.  See  also  compiling 
Microsoft  QuickC,  20 
min  macro,  77 

MK  (mouse  key)  identifiers,  137 
MLIBEW  library,  283 
MM  (mapping  mode)  identifiers,  55, 
518-19,  522-34 
modal  dialog  boxes 
Cancel  button,  431-32 
changing  child  window  controls, 
427-30 

creating  child  window  controls,  419-21 
creating  user-defined  controls,  435-43 
dialog  box  procedures,  414-16 


modal  dialog  boxes,  continued 

example  program  with  controls,  421-35 
example  program  with  simple,  408-17 
example  program  with  user-defined 
controls,  435-43 
functions,  435 
invoking,  416-17 
in  libraries,  935 

modeless  dialog  boxes  vs.,  445-47 
OK  button,  431-32 
painting  on,  434-35 
styles,  417-19 

tab  stops  and  groups,  432-34 
templates  in  resource  scripts,  412-14 
modeless  dialog  boxes 
control  IDs  in,  46l 
example  programs,  448-61 
modal  dialog  boxes  vs.,  445-47 
ModifyMenu  function,  367 
module  definition  files 

dynamic  link  libraries,  919-20 
overview,  39-40 
specifying  links,  935-36 
monochrome  bitmap  format,  621-22 
mouse 

cursors  ( see  mouse  cursors) 
detecting  presence  of,  135 
example  program  capturing,  167-74 
messages  ( see  mouse  messages) 
scrolling  with  {see  scroll  bar  controls; 

window  scroll  bars) 
terminology,  135-36 
mouse  cursors 
arrow,  136 

carets  vs.,  118  ( see  also  carets) 
changing  shape  of,  172-73 
creating  customized,  with  Image  Editor, 
313-15 

customized,  318 
default,  136 
display  count,  154-55 
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mouse  cursors,  continued 

example  program  with  customized, 
309-12 
handles,  26 
hot  spots  on,  135-36 
identifiers,  25,  31, 136 
predefined,  31 
MOUSE. DRV  driver,  908 
mouse  messages 

button  identifiers,  98,  99, 136 
button  messages  and  mouse  key  states, 
136-38 

client-area,  136-45 

coordinates  and  data  structures,  142-43 
{see  also  coordinates) 
double-clicks,  145 

example  program  with  child  windows, 
161-67 

example  program  with  hit-testing, 
150-54 

example  program  with  keyboard 
interface,  155-60 
example  program  with  simple 
processing  of,  138-42 
hit-test  identifiers,  146-48 
hit-testing,  147-48, 149-67 
keyboard  emulation,  154-55 
mouse  key  identifiers,  137 
movement  messages,  42 
nonclient-area,  146-48 
as  queued  messages,  42 
Shift  key  states,  144-45 
virtual  key  codes  for  buttons,  98,  99 
moveable  memory  segments,  278-79 
MoveTo  function,  141,  542,  544 
MoveWindow  function,  208,  435 
MSC.BAT  file,  19 
MSCDLL.BAT  file,  912 
MS-DOS 

applications  in  Windows,  10, 11 


MS-DOS,  continued 

character  sets  and  international  support, 
128-29, 132-33 

function  calls  from  Windows,  463 
MSG  data  structure,  26,  34-35 
Multiple  Document  Interface  (MDI) 
child  document  windows,  904-6 
creating  child  documents,  902-3 
data  structures,  885-87,  902-3 
destroying  menus,  906 
elements,  884-85 
example  program,  887-902 
frame  window  message  processing, 
903-4 

multiple  menu  templates,  900-901 
new  terminology,  885-86 
overview,  883 

program  initialization,  901-2 
multiple  instances,  246 
multitasking 

descriptor  tables  and,  276 
nonpreemptive,  43-44 
user  advantages,  7-8 

N 

name-mangling  and  DLLs,  918-19 
names 

application,  for  DDE  server,  824-25 
functions,  11 
variables,  27-28 
NAME  statement,  39 
naming  conventions.  See  Hungarian 
notation 

near  addresses,  274-75 
near  pointers,  274-75 
New  Executable  (EXE)  file  format,  12 
NEWFRAME  subfunction  of  Escape , 
730-31,  748,  759 

NEXTBAND  subfunction  of  Escape ,  748, 
778-79 
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NMAKE  utility,  19,  21-24 
nonclient-area  mouse  messages,  146-48 
nonpreemptive  multitasking,  43-44 
nonqueued  messages,  42-43 
nonsystem  character  messages,  109 
nonsystem  keystroke  messages,  93-94 
NOPOPUPS  example  program,  369-74 
notification  codes 
edit  controls,  231 
list  boxes,  257 

NULL-BRUSH  brush,  558-59 
NULL  icons,  197-98,  246 
NULL  menus,  345 
NULL-PEN  pen,  544 
numeric  identifiers.  See  identifiers 
numeric  keypad,  generating  ANSI 
characters  with,  133 

o 

object  libraries,  908-9 
object-oriented  programming  concepts,  13 
objects,  14.  See  also  bitmaps;  brushes; 
logical  fonts;  pens;  regions;  stock 
objects 

OEM  character  set,  128-29, 130 
OEM  scan  code,  keystroke,  94 
OemToAnsiBuff  function ,  133 
OemToAnsi  function,  129, 132-33 
OffsetClipRgn  function,  587 
OffsetRect  function,  583 
OF  (open  file)  identifiers,  464 
OFN  (open  file  name)  identifiers,  486-87 
OK  buttons,  431-32 
OLDNAMES.LIB  library,  23 
OpenClipboard  function,  794,  796 
OpenFile  function,  133,  462 
open  file  (OF)  identifiers,  464 
OPENFILENAME  data  structure,  486 
open  file  name  (OFN)  identifiers,  486-87 
ordering  file  lists,  262-63 
orientation  of  text,  692-93 


origins 

brushes,  225,  580 

windows  and  viewports,  521,  522-24 
OS/2  operating  system,  607 
OUT  (output  font)  identifiers,  695 
output.  See  display  devices;  printer  devices; 

printing;  text  output 
output  models,  15-16 
overlapping  windows,  33 
owner-draw  buttons,  213,  225-33 
OWNERDRW  example  program,  225-33 

P 

packed-DIB  format,  609-10 
paint  data  structure,  26,  38,  51-54,  496 
painting  text.  See  text  output 
paint  message.  See  WM-PAINT  message 
PaintRgn  function,  585-86 
PAINTSTRUCT  data  structure,  26,  38, 
51-54,  496 

paragraph  justification,  716-25 
parent  windows 
handles,  33,  207 

messages  from  child  windows  to,  207, 
214-15 

messages  to  child  windows  from,  215-16 
pascal  functions,  12 
PASCAL  type,  26 
PatBlt function,  174,  625-29 
pattern  block  transfers,  625-29.  See  also 
bit-block  transfers 
patterns.  See  brushes 
PeekMessage 

clipboard  and,  796 
dead  time  and,  599-601 
dynamic  link  libraries,  934 
locking  data  segments,  301 
multitasking  and,  44 
printing  abort  procedures,  and,  758-59 
pens 

colors,  549-50,  556-57 
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pens,  continued 

dashed  and  dotted,  and  gaps,  549-50 
data  structure,  547 
device  dependencies,  549 
drawing  modes  and,  550-52 
logical,  545-49 
stock,  544-45 

style  identifiers,  546-48,  560 
user-defined,  545-49 
PICKFONT  program,  681-92 
pictures,  metafile,  804-9 
pie  charts,  569-71 
Pie  function,  562-71 
pie  wedges,  563-68 
pixels 

coordinate  systems,  494-95 
device  size  and,  512-13 
PlayMetaFile  function,  647 
plotter  fonts,  669,  672 
plotters.  See  printer  devices 
POEPOEM  example  program,  329-37 
POINT  data  structure,  34, 142-43 
pointers 

data  types,  26, 143, 188 
near  and  far,  274-75 
points,  drawing,  541-42.  See  also 
coordinates 

point  size  of  fonts,  675-76 
Polygon  function,  571-72 
polygons,  571-72 
PolyLine  function,  542,  544 
PolyPolygon  function,  572 
PolyPolyLine  function,  542 
POORMENU  example  program,  363-67 
POPMENU  example  program,  358-63 
POPPAD1  example  program,  247-49 
POPPAD2  example  program,  395-405 
POPPAD3  example  program,  466-88 
POPPAD4  example  program,  725-27 
POPPAD  example  program  (final),  768-75 
popup  information,  444-45 


popup  menus,  floating,  357-63 
POPUP  statement,  343 
popup  windows,  204.  See  also  dialog 
boxes;  message  boxes 
portrait  mode,  745,  779 
position,  scrolling,  70-71 
PostMessage  function,  43 
PostQuitMessage  function,  25,  39,  42, 148 
PPOINT  type,  143 
PRECT  type,  143 
preprocessor  (RCPP.EXE),  308 
previous  instance  parameters,  29 
previous  key  state,  keystroke,  95 
PRINT1  example  program,  751-56 
PRINT2  example  program,  759-63 
PRINT3  example  program,  763-68 
printer  device  contexts.  See  also  printing 
bit-block  transfer  capabilities,  747 
creating,  735-37 
device  modes  and,  745-46 
example  program  displaying 
information  about,  498-512 
example  program  with  printer  selection, 
737-45 

information  about,  498 
overview,  734 

printer  devices.  See  also  printing 
device  contexts  ( see  printer  device 
contexts) 
fonts,  668,  786-88 
information  contexts  for,  509 
overview,  729-34 
raster  vs.  vector,  494 
print f  function,  59 
printing 

abort  procedures  ( see  abort  procedures 
in  printing) 

banding  technique  ( see  banding 
technique) 

dialog  procedures,  763-68 
error  handling,  776-77 
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printing,  continued 

error  identifiers,  750,  757-59,  776-77 
Escape  subfunctions,  747-51 
example  program  with  abort  procedure, 
759-63 

example  program  with  banding 
technique,  781-86 
example  program  with  dialog 
procedure,  764-68 
example  program  with  formfeed 
subfunction,  748-51 
example  program  with  multipage 
document  printing,  768-75 
example  program  with  simple  printing, 
751-56 

Print  Manager  program  (PRINTMAN.EXE), 
730,  732-34 

private  data  formats,  813-15 
program  instances.  See  instances,  program 
Programmer’s  Workbench,  20 
programming  concepts 

all-or-nothing  commitment,  11 
calls  to  programs  from  Windows,  41-42 
dynamic  linking,  12-13 
first  program  (seeHELLOWIN  example 
program) 

function  calls,  11-12 
learning  curve  for  Windows 
programming,  44-45 
message-driven  architecture,  13-14 
MS-DOS  applications  in  Windows,  11 
nonpreemptive  multitasking,  43-44 
object-oriented  programming,  13 
queued  and  nonqueued  messages, 

42-43 

window  procedures,  14-15 
programs.  See  application  programs 
program  segments.  See  code  segments; 

data  segments;  segments,  memory 
prologs,  far  function,  191,  927-28 
protected  mode,  275-76,  290,  291,  308-9 


PS  (pen  style)  identifiers,  546-48,  560 
PtlnRect  function,  584 
push  buttons,  216-17,  431-32 
PUSHBUTTON  statement,  420,  431 

Q 

QUERYESCSUPPORT  subfunction  of 
Escape ,  748 

queued  messages,  42-43 
QuickC.  ^Microsoft  QuickC 
quit  message,  35,  42 

R 

R2  (binary  raster  operation)  identifiers, 
550-57 

radio  buttons,  218 

RANDRECT  example  program,  601-3 

range,  scrolling,  70-71 

raster  capability  (RC)  identifiers,  510, 

511  111 

raster  devices,  484 

raster  fonts,  56,  668-69,  673 

raster  operation  (ROP)  codes 

binary  {see  binary  raster  operation 
(ROP2)  codes) 
bit-block  transfers,  629-30 
drawing  modes  and,  550 
example  program  with,  631-32 
functions  of  different,  632-34 
identifiers,  626,  630 
pattern  block  transfers,  625-28 
RC.EXE  resource  compiler,  23-24,  306-9 
RC  extension.  See  resources 
RC  (raster  capability)  identifiers,  510, 

511  111 

RCPP.EXE  preprocessor,  308 
read  function,  463 
realloc  function,  303 
real  mode,  272,  290,  291,  309 
Rectangle  function,  559-60 
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rectangles 

banding  technique  and,  778-81 
clipping  with,  53,  586-87 
data  structure,  26,  38, 143 
drawing  filled,  583-84 
example  program  drawing,  594-98 
example  program  drawing  random, 
598-603 

example  program  swapping  contents  of, 
635-38 

valid  and  invalid,  49-50 
RECT  data  structure,  26,  38, 143 
reference  counts  of  library  functions,  939 
regions 

clipping  with,  586-87 
creating  and  painting,  584-86 
example  program  with  elliptical, 

587-92 

identifiers,  585 

RegisterClass  function,  24,  29-32 
RegisterClipboardFormat  function,  815 
registering  a  window  class,  29-32 
registers.  See  CPU  registers 
registers,  segment,  274,  930 
RegisterWindowMessage  function,  488 
registration  of  window  classes,  24,  29-32 
ReleaseCapture  function,  167 
ReleaseDC function,  54,  496 
reload  thunks,  192,  278,  910 
RemoveMenu  function,  367 
repaint  message.  See  WM -PAINT  message 
repeat  count,  keystroke,  94 
replace  function,  487-88 
ReplaceText  function,  487-88 
RESOURCE1  example  program,  309-12 
RESOURCE2  example  program,  320-24 
resource  compiler  (RC.EXE),  23-24 
resources.  See  also  bitmaps;  character  string 
resources;  dialog  boxes;  fonts;  icons; 
keyboard  accelerators;  menus;  mouse 
cursors;  user-defined  resources 


resources,  continued 

compiling,  23-24,  306-9 
in  dynamic  link  libraries,  934,  939-45 
ID  number  macro,  316,  345 
memory  and,  319-24 
systemwide,  118 
types  of,  305-6 
RestoreDC function,  517 
RGB  color  values,  185-86 
RGB  macro,  185-86,  542 
RGBQUAD  data  structure,  608-9 
RGBTRIPLE  data  structure,  609 
RGN  (region)  identifiers,  585 
Ritchie,  Dennis,  15 

ROP2  codes.  See  binary  raster  operation 
(ROP2)  codes 

ROP2LOOK  example  program,  552-56 
ROP  codes.  See  raster  operation  (ROP) 
codes 

RoundRect  function,  561-62 

S 

sans  serif  fonts,  671 

SaveDC function,  517 

SB  (scroll  bar)  identifiers,  71-73,  242 

SBS  (scroll  bar  style)  identifiers,  234-35 

scaling  bitmaps,  386-87 

scaling  factors,  521 

SC  (system  command)  identifiers,  347,  367 
SCRAMBLE  example  program,  635-38 
screen  coordinates,  519-20 
screens.  See  display  devices 
ScreenToClient  function,  146,  520 
scroll  bar  controls.  See  also  window 
scroll  bars 

background  colors,  243-45 
coloring,  245 

example  program,  235-46 
icons  as  background  colors,  246 
identifiers,  242 

keyboard  interfaces  and,  242-43 
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scroll  bar  controls,  continued 
multiple  instances  and,  246 
scroll  bars  vs.,  234-35 
style  identifiers,  234-35 
window  subclassing  and,  243 
scroll  bar  (SB)  identifiers,  71-73,  242 
scroll  box  or  thumb,  69 
ScrollDC function,  49,  592-93 
Scroll  Window  function,  49,  85,  592-93 
SDK,  Windows,  19 
search  function,  487-88 
segment  addresses,  274-75 
segment  arithmetic,  297 
segment  registers,  274,  930 
segments,  memory.  See  also  global  memory 
allocation  {see  memory  allocation) 
attributes,  287-89 

code  and  data,  282-89  (see  also  code 
segments;  data  segments) 
discardable,  279 
fixed  and  moveable,  278-79 
global  memory  layout  and,  279-81 
local  memory  and,  281-82 
memory  models  and,  282-83,  285-86 
movement  problems,  286-87 
multiple  code,  283-85 
SEGMENTS  statement,  287-89 
SelectClipRgn  function,  586-87 
SelectObject  function 
fonts,  117,  385,  663-64 
metafiles,  658 
OEM  character  set,  130 
pens,  545-49 
regions,  586 

SendDlgltemMessage  function,  430 
SendMessage  function 

child  window  messages  to  parent 
windows,  207 
clipboard  and,  796 
enabling  menu  items,  403 


SendMessage  function,  continued 
keystroke  messages,  102-3 
list  boxes  and,  254-57 
messages  to  edit  controls,  252 
nonqueued  messages,  43 
serif  fonts,  671 
server  programs,  DDE 
application  name,  824-25 
clients  and,  823-24 
examples,  831-54,  867-72,  879-81 
SETABORTPROC  subfunction  of  Escape , 
748,  757 

SetBitmapBits  function,  576,  621 
SetBitmapDimension  function,  623 
SetBkColor function,  223,  550,  662 
SetBkMode  function,  118,  662 
SetBrushOrg  function,  225,  580 
SetCapture  function,  167 
SetCaretBlinkTime  function,  118 
SetCaretPos  function,  118 
SetClassWord  function,  244,  318 
SetClipboardData  function,  794-97,  810, 
813-15 

SetClipboardViewer function,  816 
SetCursor function,  172-73,  318 
SetCursorPos  function,  155 
SetDIBits  function,  619 
SetDIBitsToDevice  function,  609-18 
SetDlgltemlnt  function,  453 
SetFocus  function,  242 
SetFontMapperFlags  function,  698 
SetMapMode  function,  518 
SetMapperFlags  function,  697-98 
SetMenu  function,  345 
SetMenuItemBitmaps  function,  389 
SetMetaFileBits  function,  655 
SetPixel  function,  141,  541-42 
SetPolyFillMode  function,  572 
SetRectEmpty  function,  584 
SetRect  function,  583 
SetROP2  function,  551 
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SetScrollPos  function,  70-71,  235 
SetScrollRange  function,  70-71,  235 
SetStretchBltMode  function,  640-41 
SetSysColor function,  221-22 
SetTextAlign  function,  67,  660 
SetTextCharacterExtra  function,  663 
SetTextColor function,  223,  662 
SetTextJustification  function,  715-16, 
787-88 

SetTimer  function,  176, 179-93 
Set ViewportExt  function,  529 
SetViewportOrg  function,  522-24,  527-28 
SetWindowExt  function,  529 
SetWindowLong  function,  243 
SetWindowOrg  function,  522-24,  528 
Set WindowText  function,  218,  418 
Set  WindowWord  function,  166-67 
Shift  key 

keystroke  messages,  98-99 
mouse  messages  and,  144-45 
short  pointers,  274-75 
SHOWBIT  example  program,  941-45 
ShowCaret  function,  118-19 
ShowCursor  function,  154 
SHOWDIB  example  program,  610-18 
SHOWPOP1  example  program,  854-66 
SHOWPOP2  example  program,  873-81 
ShowWindow  function,  24,  33-34,  43, 198, 
204, 219 

show  window  (SW)  identifiers,  29,  33-34, 
198,  204 

signed  integer  type,  26 
Simonyi,  Charles,  27 
size  identifiers,  41 

slashes  (//)  as  comment  symbol,  32-33 

SLIBCEW  library,  23,  283,  909 

small  memory  model,  282-83 

SM  (system  metrics)  identifiers,  313,  549 

Software  Development  Kit,  Windows,  19 

sorting  file  lists,  262-63 

SP  (spool)  identifiers,  750,  757-59,  776-77 


spooling,  730,  732-34 

sprint f  function,  59-60,  444 

SS  (static  style)  identifiers,  233-34 

SS  register,  929-34 

stack 

dynamic  link  libraries,  930-34 
size,  40,  281-82 
STACKSIZE  statement,  40,  281 
standard  mode,  272 
STARTDOC  subfunction  of  Escape , 
730-31,  748 

static  class  window  controls,  233-34 
static  linking  vs.  dynamic  linking,  907 
static  style  (SS)  identifiers,  233-34 
status  report  example  program,  193-99 
stock  objects 
brushes,  558 
fonts,  117, 130,  663-64 
pens,  544-45 
retrieving,  31 
strcat  function,  466 
strcmp  function,  466 
strcpy  function,  466 
StretchBlt function,  171, 173,  386-87, 
628-29,  640-41 
StretchDIBits  function,  609-18 
stretching  bitmaps,  171, 173,  386-87, 
628-29,  640-41 

strings.  See  characters;  character  string 
resources 

STRINGTABLE  statement,  325 
STRLIB2  example  library,  937 
STRLIB  example  library,  911-12,  913-16, 
919 

stroke  fonts,  669,  672 
STRPROG2  example  program,  937-38 
STRPROG  example  program,  911-12, 
920-29 

structures.  See  data  structures 
STUB  statement,  40 
STYLE  statement,  413 
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subclassing,  window,  243,  251 
SW  (show  window)  identifiers,  29,  33-34, 
198,  204 

switches,  compiling,  19,  21-24, 191,  932 
Symbolic  Link  (SYLK)  format,  792 
SYSMETS1  example  program,  60-67 
SYSMETS2  example  program,  73-78 
SYSMETS3  example  program,  79-85 
SYSMETS  example  program  (final), 
100-108 

system  character  messages,  109 

system  colors,  221-22,  233 

system  command  (SC)  identifiers,  347,  367 

SYSTEM. DRV  driver,  177-78,  908 

system  font,  47,  56, 130 

system  keystroke  messages,  93-94 

system  menu 

keyboard  accelerators  and,  394-95,  884 
processing  system  commands,  363-67 
window  style  for,  418 
system  metrics  display  programs,  60-67, 
73-78,  79-85, 100-108 
system  metrics  (SM)  identifiers,  313,  549 
system  modal  dialog  boxes,  137-38,  408 
system  modal  message  boxes,  137-38 
systemwide  resources,  118 

T 

TabbedTextOut function,  660-61 
Tab  key  logic,  432-34 
tabs,  expanding,  into  spaces,  660-61 
Tag  Image  File  Format  (TIFF),  793 
TA  (text  alignment)  identifiers,  660 
TDUMP  program,  909 
teletype  output  model,  15-16 
terminal  font,  130 
text.  See  also  characters;  fonts 
in  button  controls,  218-19 
clipboard  transfers,  793-95 
creating  bitmaps  with,  385-86 
editing  ( see  edit  controls) 


text,  continued 

output  ( see  text  output) 
search  and  replace  functions,  487-88 
strings  in  list  boxes,  254-55 
text  metrics  structure,  57-58,  698-700 
text  editor  example  program,  119-27 
text  mapping  mode,  522-25 
TEXTMETRIC  data  structure,  57-58, 
698-700 

TextOut  function,  50,  54-56,  59-60,  660 
text  output.  See  also  printing 
alignment,  715-25 
alignment  identifiers,  660 
background  color  (see  background 
colors) 

character  size,  57 
client  areas  and,  47-48 
client-area  size,  67-68 
device  context  attributes,  662-63 
device  context  handles,  50-54 
drawing  functions,  38-39,  660-62 
drawing  identifiers,  25,  38-39,  234, 
661-62 

example  program,  60-67 
fonts  (see  fonts) 
formatting  (see  formatting  text) 
functions,  659-67 

Graphics  Device  Interface  and,  50-68 
(see  also  Graphics  Device  Interface 
(GDI)) 

graying  text,  664-67 
paint  information  structure,  26,  38, 
51-54,  496 

painting  and  repainting,  48-50 
TextOut  function,  50,  54-56,  59-60,  660 
thrashing,  279 
thumb,  scrolling,  69 
thunks,  192,  278,  910 
TIFF  format,  793 
tiled  windows,  885 
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time 

getting  date  and,  204 
getting  relative,  of  keystrokes,  93 
international  support  and,  205-6 
Windows  standard  vs.  real,  206 
time  function,  204 
timer 

asynchronous  interrupts  vs.,  178-79 
call-back  function  processing  of, 

186-93 

color  and,  185-86 

example  program  processing  messages 
from,  182-86 

example  program  with  call-back 
procedure,  188-93 
example  program  with  digital  clock, 
199-206 

example  program  with  free  memory 
status  report,  193-99 
infinite  loops  and,  598-99 
messages  as  queued  messages,  42 
methods  for  using,  179-93 
multitasking  and,  44 
overview,  175-79 
SYSTEM. DRV  driver  and,  177-78 
timer  IDs,  193 
uses  for,  175-76 

window  procedure  message  processing, 
179-86 

Windows  standard  time  vs.  real  time, 

206 

TLIB.EXE  program,  937 
TLINK.EXE  linker,  23 
topic  name,  DDE,  825 
toupper  function,  131 
tracking  mouse  movement,  142 
TrackPopupMenu  function,  363 
transition  state,  keystroke,  95 
TranslateAccelerator function,  390,  394-95 
TranslateMDISysAccel  function,  886,  902 
TranslateMessage  function,  24,  33, 109 


translation  tables,  129 
TrueType  fonts,  4, 129,  659,  668-70, 

673,  786 

twips,  518 ,  525,  676,  678-79 
TYPE  example  program,  119-27 
typeface  families,  670-74.  See  also  fonts 
types.  See  data  types;  handle  types 

u 

UINT  type,  26 
underlined  characters,  694 
uninitialized  static  data  memory,  281 
UnionRect  function,  584 
unlink  function,  649,  656 
UnlockData  function,  302 
UnlockResource  function,  329 
UnrealizeObject function,  225,  580-81 
unsigned  integer  type,  26 
UpdateWindow  function,  24,  34,  43,  48 
uppercase  identifiers,  25 
user  concepts 

device-independent  graphics  interface, 
9-10 

graphical  user  interface  (GUI),  5-7 
memory  management,  8-9 
MS-DOS  applications  in  Windows,  10 
multitasking,  7-8 
user-defined  buttons,  225-33 
user-defined  child  window  controls, 

435-43 

user-defined  mapping  modes 
anisotropic,  533-34 
isotropic,  529-33 
isotropic  vs.  anisotropic,  528-29 
user-defined  messages,  215-16 
user-defined  pens,  545-49 
user-defined  resources 

creating  and  using,  328-37 
example  program  with  metafiles  as, 
652-56 
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user-defined  resources,  continued 

example  program  with  text  file  as, 
329-37 

user  interface.  See  graphical  user  interface 
(GUI) 

USER  library,  12, 14,  908,  936 

V 

ValidateRect  function,  50,  586 
ValidateRgn  function,  586 
valid  rectangles,  49-50 
variable-pitch  fonts,  66,  671 
variables 

batch  files  setting  environment,  19, 
912-13 

example  program  setting  environment, 
258-61 

Hungarian  notation  naming  convention, 
27-28 

variable-width  fonts,  56 
vector  devices,  494 
vector  fonts,  669,  672 
vertical  scrolling  program,  73-78 
VGA.  See  Video  Graphics  Array 
video  adapter.  See  Color  Graphics  Adapter 
(CGA);  Enhanced  Graphics  Adapter 
(EGA);  IBM  8514/A  video  adapter; 
Video  Graphics  Array  (VGA) 
video  devices.  See  display  devices 
Video  Graphics  Array  (VGA),  186, 

313-14,  413,  512 

viewers,  clipboard.  clipboard  viewers 

viewport  coordinates,  520-22 

virtual  coordinate  systems,  494 

virtual  key  codes,  95-99, 144-45,  392 

virtual  memory,  280 

visible  buttons,  219 

VK  (virtual  key)  identifiers,  95-99, 

144-45,  392 
vsprintf  function,  444 


W 

WaitMessage  function,  44,  301 

Walden,  Jeff  793 

warm  links,  828-30 

WHATSIZE  example  program,  534-39 

whole-window  coordinates,  520 

window  captions,  33 

window  classes 

child  window  control  {see  child  window 
controls) 

class  style  identifiers,  25,  30, 145,  516-17 
data  structure,  26,  29-32 
overview,  14 

registering,  24-25,  29-32 
registering,  in  libraries,  934 
style  identifiers,  25,  30, 145,  516-17 
window  controls.  See  child  window 
controls 

window  coordinates,  520-22 
window  message  identifiers.  See  WM 
(window  message)  identifiers 
window  procedures 

child  windows  {see  child  window 
procedures) 

default  {see  DefWindowProc  function) 

example,  66-67 

forward  declaration,  28 

MDI  frame,  903-4 

overview,  14-15,  36-39 

processing  timer  messages  with,  179-86 

setting,  30 

setting  new,  243,  251 
windows 

child  {see  child  windows) 

classes  {see  window  classes) 

client  area  {see  client  area) 

coordinates,  520-22 

creating  {see  CreateWindow  function) 

destroying,  39, 148 

displaying,  29,  33-34 

elements  of,  6-7, 13 
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windows,  continued 
handles,  26 

input  focus  and  active,  92 
MDI,  884-85 
menu  handle,  33 
messages  ( see  messages) 
minimizing,  to  icons,  198 
overlapping,  33 

paint  information  structure,  26,  38, 
51-54,  496 

painting  and  repainting,  48-50  ( see  also 
WM  _PAINT  message) 
painting  text  ( see  text  output) 
popup,  204  ( see  also  dialog  boxes; 
message  boxes) 

scroll  bars  {see  window  scroll  bars) 
show  window  indentifiers,  24,  33-34, 
43, 198,  204 
size  identifiers,  41 
static  style  identifiers,  233-34 
storing  position  and  size  of,  232 
style  {see  window  style  (WS)  identifiers) 
subclassing,  243,  251 
typical  elements  of,  6-7, 13 
Windows  (programming  environment) 
all-or-nothing  programming 
commitment,  11 

applications  {see  application  programs) 
calls  to  programs  from,  41-42 
character  sets  {see  character  sets) 

C  language  and  {see  C/C++) 
concepts  of,  for  programmers,  10-15 
concepts  of,  for  users,  5-10 
conceptual  hurdles  for  programming  in, 
40-45 

device-independent  graphics  interface 
concepts,  9-10  {see  also  Graphics 
Device  Interface  (GDI)) 
dynamic  linking  concepts,  12-13  {see 
also  dynamic  link  libraries  (DLLs)) 
executing  other  programs  from,  463 


Windows  (programming  environment), 
continued 

function  call  concepts,  11-12 
functions,  a  few  described,  24-25 
graphical  user  interface  (GUI)  concepts, 
5-7 

header  file  {see  WINDOWS.H  header 
file) 

history  and  versions  of,  4 
Image  Editor,  197,  313-15 
input  {see  child  window  controls; 

keyboard;  mouse;  timer) 
international  support  {see  international 
support) 

learning  curve  for  programming  in, 
44-45 

memory  management  concepts,  8-9 
{see  also  memory;  memory 
management) 

message-driven  architecture  concepts, 
13-14  {see  also  messages) 

MS-DOS  applications  in,  10, 11 
Multiple  Document  Interface  {see 
Multiple  Document  Interface  (MDI)) 
multitasking  concepts,  7-8 
New  Executable  file  format,  12 
nonpreemptive  multitasking  concepts, 
43-44 

object-oriented  programming 
concepts,  13 
overview,  3-4 

procedures.  See  window  procedures 
queued  and  nonqueued  message 
concepts,  42-43 
Software  Development  Kit,  19 
window  procedures,  14-15  {see  also 
window  procedures) 
window  scroll  bars.  See  also  scroll  bar 
controls 

example  program  with  horizontal, 
79-85 
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window  scroll  bars,  continued 
example  program  with  keyboard 
interface,  102-8 

example  program  with  vertical,  73-78 
identifiers,  71-73 
keyboard  interface,  85, 100-103 
messages,  71-73 

messages  and  repainting  client  areas,  78-79 
range  and  position,  70-71 
scroll  bar  controls  vs.,  234-35 
terminology,  69-70 
WINDOWS.H  header  file 

data  types,  25-26, 143, 188,  290 
function  declarations,  11 
handle  types  ( see  handle  types) 
identifiers  ( see  identifiers) 
including,  28 
resources  and,  308 

Windows  Software  Development  Kit,  19 
window  style  (WS)  identifiers.  See  WS 
(window  style)  identifiers 
window  subclassing,  243,  251 
Window  submenu,  885 
WinExec  function,  463 
WIN. INI  file 

international  support  section,  205-6 
printer  devices,  509,  733,  735-37 
WinMain  function,  24,  28-29 
WINSTUB.EXE  program,  40 
WM -COMMAND  message 
dialog  box  and,  4l6 

edit  control  notification  codes  and,  251 
keyboard  accelerators  and,  389-90,  395 
WM  (window  message)  identifiers 
character  message,  42, 109,  111-12 
client-area  mouse  messages,  136-37 
clipboard  messages,  812,  814,  816,  817 
color  message,  223-25,  245 
command  message  ( see 

WM_COMMAND  message) 


WM  (window  message)  identifiers, 
continued 

DDE  messages,  825-30,  847-55,  864-6( 

device-mode-change  message,  509,  714 

dialog  box  messages,  415 

draw  item  message,  212-13,  232 

edit  messages,  252 

font  message,  714 

input  focus  messages,  92, 119, 

154-55,  220 

keypress  messages,  42,  93,  99-103 
MDI  messages,  885-86,  902-6 
menu  messages,  346-48,  389,  395,  405 
mouse  hit-test  messages,  147-49 
nonclient-area  mouse  messages,  146 
overview,  25,  35-36 
paint/repaint  message  {see  WM_PAINT 
message) 

scrolling  messages,  71-73 
system  command  message,  42,  346, 

363,  367,  394-95 
system  messages,  42,  93-94, 109, 

111-12,  663 

timer  message  {see  timer) 
user-defined  messages,  215-16 
window  messages,  35,  39,  42,  43,  58-60, 
68, 148, 199,  248,  447 
WIN. INI  change  message,  205-6 
WM  _PAINT  message 

dead-time  processing,  598-601 
device  context  and,  496-97 
multitasking  and,  44 
painting  text  and,  48-49 
processing,  37-39,  43 
as  queued  message,  42 
structuring  programs  to  repaint  with, 
78-79 

WNDCLASS  data  structure,  26,  29-32 
WndProc  function.  See  window 
procedures 
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workspace,  884.  See  also  client  area 
wParam  message  parameter 
character  messages,  109 
example  program  displaying,  209-20 
keystroke  messages,  95-98 
mouse  messages,  137, 146 
overview,  35,  41-42 
scroll  bar  messages,  71-73 
WS  (window  style)  identifiers 
child  windows,  244 
dialog  boxes,  413-14,  417-19,  432, 

446,  460 

document  windows,  885 
overlapped  windows,  33 
overview,  25 
popup  windows,  204 
scroll  bars,  70 
system  menus,  363 
WWM  file,  283 

WYSIWYG  (what  you  see  is  what  you  get), 
5,  659 


X 

Xerox  Palo  Alto  Research  Center,  5 
XTYP  (exchange)  identifiers,  866,  879-81 
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Enhance  The  Visual  I.Q.  «s^ 
Of  Your  Applications  4 
With  Windows  Controls 


Windows  controls  elevate  a  graphical  user  interface  to  a  higher 
plane.  Nothing  can  make  your  application  bolder,  brighter,  and 
more  visual— faster— than  knowing  how  to  use  the  full  array 
of  Windows  controls  to  your  advantage.  Now,  there’s  a  video 
course  to  help  you  fast  forward  through  programming  techniques 
using  the  controls  in  the  Microsoft*  Windows™  operating  system. 
The  Microsoft  University  Exploring  Controls  video  course 
examines  various  Windows  controls,  including  buttons,  combo 
boxes,  static  controls,  scroll  bars,  edit  controls,  list  boxes, 
and  custom  controls.  Concepts  are  visually  illustrated  through 
3-D  animation  and  supported  with  hands-on  lab  exercises  and 
a  student  guide. 

Learn  how  to  modify  and  customize  controls 

▲  Apply  techniques  for  creating,  managing,  and  using  common 
control  components  of  the  Windows  environment. 

▲  Explore  how  to  modify  controls  through  advanced  techniques 
for  use  when  a  standard  Windows  control  doesn’t  meet  an 
application’s  requirements. 

a  Learn  about  subclassing,  owner  draw  controls,  and  what  it 
takes  to  create  your  own  custom  controls. 

Get  up  to  speed  quickly 

Software  developers  are  on  a  critical  path  where  bringing  a 
product  to  market  a  few  days  late  can  mean  missing  the  mark 
completely.  Video  training  from  Microsoft  University  offers  the 
flexibility  to  meet  your  needs.  Each  module  includes: 
a  Reference  information  about  the  control,  such  as  styles, 
messages,  and  notifications. 

a  Procedural  techniques  for  actually  implementing  the  control. 
a  Lab  exercises  with  sample  code  that  you  can  incorporate  into 
your  applications  immediately. 

Exceptional  training  at  a  price 
that’s  under  control 

This  video  course  will  save  you  countless  development  man 
hours  while  helping  you  improve  the  appearance  and  usability  of 
your  applications.  So  bring  the  Microsoft  University  classroom 
in-house,  and  take  advantage  of  this  intelligent  training  solution. 
The  complete  Exploring  Controls  video  course  is  just  $199*  and 
includes  one  student  guide.  To  leverage  your  training  investment 
across  a  development  team,  you  can  purchase  additional  student 
guides  for  just  $49  each. 

Expertise  at  the  touch  of  a  button 

If  you  want  to  understand  Windows  controls  from  the  inside  out, 
pop  in  the  videotape,  hit  play,  and  turn  up  the  volume.  You’ll 
learn  from  the  training  experts  at  Microsoft,  developer  of  the 
most  popular  applications  for  Windows.  Now,  put  the  power 
of  Windows  controls  to  work  in  YOUR  applications— order  your 
copy  of  the  Exploring  Controls  video  course  today. 

*Plus  shipping  and  applicable  state  sales  taxes. 


TO  ORDER: 


CALL  (206)  828-1507 

Once  your  representative  answers,  please  mention  department  605. 


Microsoft  University  offers  technical  training  for  developers  and 
support  professionals.  Please  call  for  more  information  on  other 
video  courses,  classroom  courses  at  nine  convenient  locations  in 
the  U.S. ,  on-site  training,  licensing  programs,  custom  courses, 
Management  Education  seminars,  or  the  Microsoft  University 
Training  Alliance  member  nearest  you. 
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248  pages,  softcover  with  two  1.44-MB  3.5-inch  disks 
ISBN  1-55615-439-9 
$39.95*  ($54.95  Canada) 

This  book  contains  the  Microsoft  guidelines  for  creating  well-designed,  consistent  user  interfaces 
for  applications  that  run  on  the  Microsoft  Windows  version  3.1  operating  system.  It’s  an  essen¬ 
tial  reference  for  all  programmers  and  designers  working  on  applications  for  Windows,  regard¬ 
less  of  experience  level  or  development  tool  used. 

Beginning  with  the  basic  principles  of  user  interface  design,  the  book  moves  from  discussions  of 
mouse  and  keyboard  input  elements  to  detailed  information  on  the  major  elements  of  the  user 
interface.  The  concluding  chapters  cover  Windows  for  Pen  Computing  and  several  other  impor¬ 
tant  topics,  such  as  adding  Help  systems  and  providing  ways  for  users  to  customize  the  interface. 
If  you’re  developing  applications  for  Microsoft  Windows,  this  book  will  be  a  key  resource. 

Bundled  with  the  book  is  a  set  of  companion  disks. 

They  include  the  following  materials: 


THE  WINDOWS 
INTERFACE 


An  Application  Design  Guide 


Interactive  Design  Guide 

A  demonstration  application 
that  incorporates  the  ideas  and 
recommendations  presented  in 
The  Windows  Interface  Design 
Guide.  It  also  includes  an  online 
version  of  this  book’s  contents 
with  powerful,  full-text  search¬ 
ing  capabilities  for  instant  access 
to  all  areas  the  user  is  interested 
in  locating. 


Visual  Design  Guide 

This  online  reference  comple¬ 
ments  The  Windows  Intel  face 
Design  Guide.  It  focuses  on 
artistic  considerations,  such  as 
how  to  use  color  effectively, 
how  to  design  icons,  and  how 
to  make  buttons  look  raised, 
depressed,  or  inactive.  It  also 
contains  examples  of  visuals, 
including  toolbars,  icons,  and 
different  types  of  buttons. 


Buttons  and  Cursors 

This  is  a  collection  of  images 
that  developers  can  incorporate 
directly  into  their  applications. 
The  disk  also  comes  with  a 
dynamic  link  library  (DLL)  that 
can  create  all  states  of  a  button 
from  a  bitmap  of  the  button’s 
surface  area.  The  disk  includes 
a  license  agreement,  allowing 
developers  to  use  the  images  and 
the  DDL  in  their  products 
royalty-free. 
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memory  (i.e.,  RAM)  or  installed  into  the  permanent  memory  (e.g.,  hard  disk,  CD-ROM,  or  other  storage  device)  of  that  computer.  You  may  not  network 
the  SOFTWARE  or  otherwise  use  it  on  more  than  one  computer  or  computer  terminal  at  the  same  time. 

2.  COPYRIGHT.  The  SOFTWARE  is  owned  by  Microsoft  or  its  suppliers  and  is  protected  by  United  States  copyright  laws  and  international  treaty 
provisions.  Therefore,  you  must  treat  the  SOFTWARE  like  any  other  copyrighted  material  (e.g.,  a  book  or  musical  recording)  except  that  you  may  either 
(a)  make  one  copy  of  the  SOFTWARE  solely  for  backup  or  archival  purposes,  or  (b)  transfer  the  SOFTWARE  to  a  single  hard  disk  provided  you  keep 
the  original  solely  for  backup  or  archival  purposes.  You  may  not  copy  the  written  materials  accompanying  the  SOFTWARE. 

3.  OTHER  RESTRICTIONS.  You  may  not  rent  or  lease  the  SOFTWARE,  but  you  may  transfer  the  SOFTWARE  and  accompanying  written  materials 
on  a  permanent  basis  provided  you  retain  no  copies  and  the  recipient  agrees  to  the  terms  of  this  Agreement.  You  may  not  reverse  engineer,  decompile, 
or  disassemble  the  SOFTWARE.  If  the  SOFTWARE  is  an  update  or  has  been  updated,  any  transfer  must  include  the  most  recent  update  and  all  prior 
versions. 

4.  DUAL  MEDIA  SOFTWARE.  If  the  SOFTWARE  package  contains  both  3.5"  and  5.25"  disks,  then  you  may  use  only  the  disks  appropriate  for  your 
single-user  computer.  You  may  not  use  the  other  disks  on  another  computer  or  loan,  rent,  lease,  or  transfer  them  to  another  user  except  as  part  of  the 
permanent  transfer  (as  provided  above)  of  all  SOFTWARE  and  written  materials. 

5.  SAMPLE  CODE.  If  the  SOFTWARE  includes  Sample  Code,  then  Microsoft  grants  you  a  royalty-free  right  to  reproduce  and  distribute  the  sample 
code  of  the  SOFTWARE  provided  that  you:  (a)  distribute  the  sample  code  only  in  conjunction  with  and  as  a  part  of  your  software  product;  (b)  do  not  use 
Microsoft’s  or  its  authors’  names,  logos,  or  trademarks  to  market  your  software  product;  (c)  include  the  copyright  notice  that  appears  on  the  SOFTWARE 
on  your  product  label  and  as  a  part  of  the  sign-on  message  for  your  software  product;  and  (d)  agree  to  indemnify,  hold  harmless,  and  defend  Microsoft 
and  its  authors  from  and  against  any  claims  or  lawsuits,  including  attorneys’  fees,  that  arise  or  result  from  the  use  or  distribution  of  your  software  product. 

DISCLAIMER  OF  WARRANTY 

The  SOFTWARE  (including  instructions  for  its  use)  is  provided  “AS  IS”  WITHOUT  WARRANTY  OF  ANY  KIND.  MICROSOFT  FURTHER 
DISCLAIMS  ALL  IMPLIED  WARRANTIES  INCLUDING  WITHOUT  LIMITATION  ANY  IMPLIED  WARRANTIES  OF  MERCHANT¬ 
ABILITY  OR  OF  FITNESS  FOR  A  PARTICULAR  PURPOSE.  THE  ENTIRE  RISK  ARISING  OUT  OF  THE  USE  OR  PERFORMANCE 
OF  THE  SOFTWARE  AND  DOCUMENTATION  REMAINS  WITH  YOU. 

IN  NO  EVENT  SHALL  MICROSOFT,  ITS  AUTHORS,  OR  ANYONE  ELSE  INVOLVED  IN  THE  CREATION,  PRODUCTION,  OR 
DELIVERY  OF  THE  SOFTWARE  BE  LIABLE  FOR  ANY  DAMAGES  WHATSOEVER  (INCLUDING,  WITHOUT  LIMITATION, 
DAMAGES  FOR  LOSS  OF  BUSINESS  PROFITS,  BUSINESS  INTERRUPTION,  LOSS  OF  BUSINESS  INFORMATION,  OR  OTHER 
PECUNIARY  LOSS)  ARISING  OUT  OF  THE  USE  OF  OR  INABILITY  TO  USE  THE  SOFTWARE  OR  DOCUMENTATION,  EVEN  IF 
MICROSOFT  HAS  BEEN  ADVISED  OF  THE  POSSIBILITY  OF  SUCH  DAMAGES.  BECAUSE  SOME  STATES/COUNTRIES  DO  NOT 
ALLOW  THE  EXCLUSION  OR  LIMITATION  OF  LIABILITY  FOR  CONSEQUENTIAL  OR  INCIDENTAL  DAMAGES,  THE  ABOVE 
LIMITATION  MAY  NOT  APPLY  TO  YOU. 

U.S.  GOVERNMENT  RESTRICTED  RIGHTS 

The  SOFTWARE  and  documentation  are  provided  with  RESTRICTED  RIGHTS.  Use,  duplication,  or  disclosure  by  the  Government  is  subject  to 
restrictions  as  set  forth  in  subparagraph  (c)(l)(ii)  of  The  Rights  in  Technical  Data  and  Computer  Software  clause  at  DFARS  252.227-7013  or 
subparagraphs  (c)(1)  and  (2)  of  the  Commercial  Computer  Software  —  Restricted  Rights  48  CFR  52.227-19,  as  applicable.  Manufacturer  is 
Microsoft  Corporation,  One  Microsoft  Way,  Redmond,  WA  98052-6399. 

If  you  acquired  this  product  in  the  United  States,  this  Agreement  is  governed  by  the  laws  of  the  State  of  Washington. 

Should  you  have  any  questions  concerning  this  Agreement,  or  if  you  desire  to  contact  Microsoft  Press  for  any  reason,  please  write:  Microsoft  Press, 
One  Microsoft  Way,  Redmond,  WA  98052-6399. 

5.25-inch  disk  for  Programming  Windows' 3.1 

You  can  order  the  enclosed  disk  in  5.25-inch  format  (one  1 .2-MB  disk) — free  of  charge.  Include  only  shipping  charges  of  $5.00 
per  disk.  To  order,  request  item  number  097-000-751.  Send  your  name  and  address  (no  P.O.  Boxes  please),  and  daytime  phone 
number  along  with  your  check  or  money  order  for  shipping  (U.S.  funds  only)  to:  Microsoft  Press,  Attn:  Programming  Windows 
3.1  disk.  One  Microsoft  Way,  Redmond,  WA  98052-6399.  Allow  2-3  weeks  for  delivery.  Offer  valid  in  the  U.S.  only. 


